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Chapter 1 Introduction 


TIBCO JasperReports® Server builds on TIBCO JasperReports® Library as a comprehensive family of Business 
Intelligence (BI) products, providing robust static and interactive reporting, report server, and data analysis 
capabilities. These capabilities are available as either stand-alone products, or as part of an integrated end-to-end 
BI suite utilizing common metadata and provide shared services, such as security, a repository, and scheduling. 
The server exposes comprehensive public interfaces enabling seamless integration with other applications and 
the capability to easily add custom functionality. 


This section describes functionality that can be restricted by the software license for JasperReports 
Server. If you don’t see some of the options described in this section, your license may prohibit you from 
using them. To find out what you're licensed to use, or to upgrade your license, contact Jaspersoft. 


The heart of the TIBCO Jaspersoft® BI Suite is the server, which provides the ability to: 

• Easily create new reports based on views designed in an intuitive, web-based, drag and drop Ad Hoc 
Editor. 

• Efficiently and securely manage many reports. 

• Interact with reports, including sorting, changing formatting, entering parameters, and drilling on data. 

• Schedule reports for distribution through email and storage in the repository. 

• Arrange reports and web content to create appealing, data-rich Jaspersoft Dashboards that quickly convey 
business trends. 

For users interested in multi-dimensional modeling, we offer Jaspersoft® OLAP, which runs as part of the server. 

While the Ad Hoc Editor lets users create simple reports, more complex reports can he created outside of the 

server. You can either use Jaspersoft® Studio or manually write JRXML code to create a report that can be ran 

in the server. We recommend that you use Jaspersoft Studio unless you have a thorough understanding of the 

JasperReports file structure. 

You can use the following sources of information to leam about JasperReports Server: 

• Our core documentation describes how to install, administer, and use JasperReports Server and Jaspersoft 
Studio. Core documentation is available as PDFs in the doc subdirectory of your JasperReports Server 
installation. You can also access PDF and HTML versions of these guides online from the Documentation 
section of the Jaspersoft Community website. 

• Our Ultimate Guides document advanced features and configuration. They also include best practice 
recommendations and numerous examples. You can access PDF and HTML versions of these guides online 
from the Documentation section of the Jaspersoft Community website. 
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• Our Online Learning Portal lets you learn at your own pace, and covers topics for developers, system 
administrators, business users, and data integration users. The Portal is available online from the Professional 
Services section of our website . 

• Our free samples, which are installed with JasperReports Library, Jaspersoft Studio, and JasperReports 
Server, are available and documented online. Please visit our GitHub repository . 

• If you have a subscription to our professional support offerings, please contact our Technical Support team 
when you have questions or ran into difficulties. They're available on the web at and through email at 
http://support.tibco.com and js-support@tibco.com . 

JasperReports Server is a component of both a community project and commercial offerings. Each integrates the 

standard features such as security, scheduling, a web services interface, and much more for running and sharing 

reports. Commercial editions provide additional features, including Ad Hoc views and reports, advanced charts, 

dashboards, Domains, auditing, and a multi-organization architecture for hosting large BI deployments. 

This chapter contains the following sections: 

• Conventions 

• JasperReports Server Distributions 

• Release Notes 

• System Requirements 

• Support for Internationalization 


.1 Conventions 

This document uses the following conventions when referring to file locations: 


Convention 

Description 

<js-install> 

For binary installations, the directory where JasperReports Server will be 
installed by the binary installer. This directory contains directories for 
applications used by the installer, such as apache-tomcat and postgresql, as 
well as directories for JasperReports Server, such as docs and samples. 

For manual installations, the directory where you unpack the WAR file 
distribution TIBJs-jrs-cp_7.8.0_bin.zip. 

<java> 

The directory where Java is installed. 

<jboss> 

The directory where JBoss is installed. 

<postgresql> 

The directory where PostgreSQL is installed. If you use our bundled instance of 
PostgreSQL, it's in the <js-install> directory. 

<tomcat> 

The directory where Apache Tomcat is installed. If you use our bundled instance 
of Tomcat, it's in <js-install> directory. 
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2 JasperReports Server Distributions 

You can install JasperReports Server either by running an executable installer or deploying a WAR file. For 
evaluations, we recommend the installer; for most production instances, we recommend the WAR file. Both the 
executable and the WAR file are available from the Jaspersoft community site (http://community.jaspersoft.com). 

• The binary installer installs JasperReports Server, automatically configures the JasperReports Server 
database, and optionally installs the sample data for working with tutorials. It uses the Tomcat application 
server and the PostgreSQL database. There are native installers for Linux, Macintosh, and Windows. See the 
JasperReports Server Supported Platform Datasheet for the list of supported operating systems and other 
components. See Chapter 2, “Installing Using the Binary Installer,” on page 11 for more information. 

• The WAR file binary distribution contains the JasperReports Server web archive file and the scripts to 
create and load the database. The WAR file distribution supports additional applications not supported by 
the installers. For a list of supported JDK/JVMs, application servers, databases, operating systems, and 
browsers, refer to the JasperReports Server Supported Platform Datasheet. See Chapter 3, “Installing the 
WAR File Distribution,” on page 27 for information on installing the WAR file. 


& 


Fora complete list of applications supported by the WAR file distribution, see the JasperReports Server 
Supported Platform Datasheet. 


3 Release Notes 

Release notes are included with each distribution and with each new update to a distribution. 

Not all applications are immediately supported when a new JasperReports Server version is released. For 
instance, some applications require additional testing beyond what is completed for the initial General 
Availability (GA) release. To find out exactly what applications are supported with a particular distribution 
refer to the release notes in that distribution. 


4 System Requirements 

The following table contains the minimum and recommended resources for a full installation that includes 
PostgreSQL and an application server. The values are based on our own testing. You may find that 
JasperReports Server can ran on systems with fewer resources or slower systems than stated in the minimum 
resources column. At the same time, it's possible to run out of resources with the recommended configuration. 
The success of your deployment depends on the intended load of the system, the number of concurrent users, the 
data sets, and whether the databases are installed on the same system as the JasperReports Server. 


Resource 

Footprint 

Minimum 

Recommended 

Disk 

-1.5 

Gigabytes 

10GB free 

40GB + 

RAM 

8GB 

12GB + 

Processor 

2 core 

minimum 

2.5GHz + multi-core Pentium for Windows, Mac, and 

Linux 
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For additional system requirements, including Java version, see the JasperReports Server Supported Platform 
Datasheet. 


1.5 Support for Internationalization 

JasperReports Server supports the full Unicode character set using UTF-8 encoding. It also depends on the 
underlying database and application server to support the UTF-8 character encoding. UTF-8 is configured by 
default in the bundled Tomcat and PostgreSQL software. If you use any other software, refer to the 
JasperReports Server Community Project Administrator Guide for instructions about configuring software to 
support UTF-8. 
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To install JasperReports Server, you can use the binary installer, which is available for Windows, Linux, and 
Mac. The binary installer installs JasperReports Server, automatically configures the JasperReports Server 
database, and optionally installs the sample data for working with tutorials. It uses the Tomcat application 
server and the PostgreSQL database. 

Double-click the installer and accept the default installation type to create a standard installation. Select the 
custom installation to specify the Tomcat application server and/or PostgreSQL instance to use, among other 
options. The installer can also be ran from the command line. 

This chapter includes the following sections: 

• Installation Requirements 

• Choosing Installer Components 

• Choosing Sample Data 

• Installation 

• Post-Installation Tasks 

• Starting and Stopping the Server 

• Logging into JasperReports Server 

• Uninstalling the Server 




The bundled installer is not meant for use in enterprise production environments. It is recommended for 
evaluation purposes. 


2.1 Installation Requirements 

Before installing the product on your system, ensure that you can log in to the system with appropriate 
permissions, and that your system meets the hardware and software requirements needed to install JasperReports 
Server. See the JasperReports Server Supported Platform Datasheet for more information. 

2.1.1 Pre-installation Tasks 

Pre-installation tasks include the tasks that you must complete before you start the installer, such as ensuring 
your system meets the installation requirements. If you want to use existing versions of any component software, 
you must also prepare them, as described in later sections. 
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2.1.1.1 Download JasperReports Server Software 

Download the JasperReports Server software package for your platform from the Download section of the 
Jaspersoft Community website. Extract the JasperReports Server archive file to a temporary directory on the 
machine on which you will run the installer. 

The installers have the following file names: 

* SIB_js-jrs-cp_7.8.0_win_x86_64.exe 

* fIB_js-jrs-cp_7.8.0_linux_x86_64.run 

* fIB_js-jrs-cp_7.8.0_macosx_x86_64.zip 


2.1.2 Installation Account 

The privileges required to install the product differ for Windows and UNIX platforms. Ensure that you have the 
appropriate privileges to install on the target platform. 

2.1.2.1 Microsoft Windows 

You must have administrator privileges for the machine on which you want to install the software. Right-click 
the binary installer file and select “Run as administrator’ from the context menu. 


SI 


The Windows installer will get an error installing the PostgreSQL database if the Windows user does not 
have sufficient administrative privileges and if the installer is not started by right-clicking to use “Run as 
administrator”. 


2.1.2.2 UNIX 

In Linux, the installer is a . run file; you can run it from the command line or from a graphical environment. 
Any non-root user can perform the installation. 

2.1.2.3 Mac 

In Mac OSX, the installer is a .zip file. After download, you should find the installer already unpacked in your 
<user>/Downloads folder. Double-click the following: 

TIB_js-jrs-cp_7.8.0_macosx_x86_64.app 


2.2 Choosing Installer Components 

The installer is designed to get JasperReports Server up and running quickly. The server requires an application 
server and a database. The installation executable lets you choose whether to install bundled components or use 
versions of these already present on your system. 

2.2.1 Bundled Components 

The installer distribution bundles the following components: 
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Component 

Description 

JasperReports Server 
Application 

WAR file and configuration support scripts. 

JasperReports Server 
Documentation 

Found in the <js-install>/docs directory. 

Apache Tomcat 

Web application container. You can use the bundled version or an existing version. 

PostgreSQL Database 

Database server. You can use the bundled version or an existing version. 


2.2 Preparing Existing Components 

You can use components you have installed previously. Make sure that you are using supported versions of the 
components. For information about specific versions of third-party applications supported by the installer, refer 
to the JasperReports Server Supported Platform Datasheet. 

• Tomcat application server - If you want to use an existing Tomcat, it must be on the local machine. See 
2.2.3, “Selecting a Tomcat Configuration,” on page 13 for more information. 

• PostgreSQL database - If you want to use an existing PostgreSQL, it can be on a local or remote machine. 
If it’s on a remote Linux machine, configure PostgreSQL to allow remote connections as described in 
2.2.4.4, “Enabling Connections to a Remote Host,” on page 16. See 2.2.4, “Selecting a PostgreSQL 
Configuration,” on page 14 for more information. 

• Chrome/Chromium browser - See 2.2.5, “Selecting a Chrome/Chromium Configuration,” on page 16 for 
more information. 


& 


If you want to use an existing PostgreSQL database instance, the database must be running at install 
time. If you wantto use an existing Apache Tomcat, the Tomcat instance must be stopped. 


If you choose to install the bundled Tomcat and database, both are installed on the same host as the server. 


2.3 Selecting a Tomcat Configuration 

JasperReports Server requires an application server. The installer is configured to ran with the Apache Tomcat 
server. You can choose to use a bundled Tomcat or an existing Tomcat. 

2.2.3.1 Bundled Tomcat 

If you select I want to use the bundled Tomcat, the installer puts an instance of Tomcat onto your system. If 
you are prompted for Tomcat's server port and shutdown port, you can accept the default values or enter 
alternate values. If a port is already in use, you will receive an error. The installer looks for open Tomcat ports 
from 8080 up. 

2.2.3.2 Existing Tomcat 

If you want to use an existing Tomcat application server, I want to use an existing Tomcat. Later you will 
be prompted for the location of Tomcat. Browse to the folder where you installed Tomcat. Make sure that the 
existing Tomcat is not running. When you are prompted for Tomcat's server port and shutdown port, you can 
accept the default values or enter alternate values. 
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2.2.4 Selecting a PostgreSQL Configuration 

JasperReports Server requires a database. The installer is pie-configured to run with the PostgreSQL database. 
You have two options: 

• Use the bundled PostgreSQL 

• Use an existing PostgreSQL 

2.2.4.1 Choosing the Bundled PostgreSQL 

If you install the bundled PostgreSQL, the installer puts PostgreSQL onto your system. The default PostgreSQL 
port is 5432. If port 5432 is in use, the installer will prompt you to pick an alternate port. 

The installer sets the PostgreSQL administrator password to postgres and creates a PostgreSQL database user 
with administrator privileges and the credentials jasperdb/password. 

The following table summarizes the parameters set during installation of the bundled PostgreSQL: 


Parameter 

Default Value and Description 

Binary Directory 

The directory where the PostgreSQL and pgAdmin binaries are 

located. 

Port 

The port number PostgreSQL uses (default is 5432). Choose an 
alternate port if 5432 is in use. 

IP or Host Name 

The IP address or name of the machine where PostgreSQL is installed. 
The default value is 127.0.0.1. 

PostgreSQL Administrative 

Password 

Password ofthe database administrative user: password. 

The installer cannot handle special characters at the end of a 
password string. Incompatible characters include: & ; $ 

Database User Name 

Hard coded default: jasperdb - The installer creates this user which is 
used to connect to the JasperReports Server database 

Database User Password 

Hard coded default: password - The installer uses this password for 
the jasperdb user. 

Additional notes for Linux 

If your Linux installation does not have a locale setting that supports 
UTF-8 encoding, your bundled PostgreSQL instance will be initialized 
using a temporary locale (— locale=c). This will allow the 

PostgreSQL initdb to succeed with the desired UTF-8 database 
encoding. 


2.2.4.2 Choosing an Existing PostgreSQL on a Local Host 

If you choose to use an existing PostgreSQL database, you'll he prompted for the location of PostgreSQL and 
the port to use. If you have an instance of PostgreSQL installed locally, accept the default, which is 127.0.0.1, 
the localhost. Accept the default location for the PostgreSQL \bin directory, or click Browse to select another 
location. You'll also be prompted for the default administrative account password of the PostgreSQL 
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administrative user. The database administrative user account name postgres is used by default. Enter the 
database administrative user password and click Enter. 


& 


If the installer displays an error message saying FATAL: password authentication failed for user postgres, 
try reentering the administrative password for your PostgreSQL database. 


The following table summarizes the parameters set during the installation of an existing PostgreSQL. 


Defaults Used 

Hard-coded Default Values Used or Created 

PostgreSQL Administrative User 

Name 

postgres - The default administrative database user. 

jasperserver Database User Name 

jasperdb - The installer creates this database user to connect to 
jasperserver database. 

jasperserver Database User 

Password 

password - The installer creates this password for the jasperdb 
database user. 


To improve system security, Jaspersoft recommends that you change the default password for 
jasperdb as soon as possible. To change the jasperdb connection password in JasperReports 
Server, edit: <js-install>/apache-tomcat/jasperserver/META-INF/context.xml. (And delete: <js- 
install>/apache-tomcat/conf/Catalina/localhost/jasperserver.xml, if it exists.) Then make the same 
change in PostgreSQL using pgAdmin or psql. 


2.2.4.3 Using an Existing PostgreSQL on a Remote Host 

If you're installing to a remote instance of PostgreSQL, you need to have the PostgreSQL client tools on your 
local machine. The client tools version should match the version of your remote PostgreSQL. You can check the 
version of PostgreSQL instance by entering this command on the computer where it’s installed: 

psql —version 

or 

<path-to-postgresql-bin-folder>/psql —version 
For instance: C : /Jaspersoft/PostgreSQL/9.0/bin/psql —version 

To verify that you can connect to the target remote PostgreSQL from the local installation 
machine: 

• Using your local PostgreSQL client tools, enter this command: 

psql -U postgres -h <remote-host> -d postgres 

or 

<path-to-postgresql-bin-folder>/psql *11 postgres -h <remote-host> -d postgres 

You might also need to enable connections as described below. 
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2.2.4.4 Enabling Connections to a Remote Host 

On most platforms, the default PostgreSQL installation doesn’t allow remote connections for security reasons. 
You need to enable remote connections as described in this documentation: 

• The PostgreSQL configuration documentation on the PostgreSQL web site 

• The \docs directory of your PostgreSQL installation 

To enable connections from the installation machine to the remote PostgreSQL server: 

1. Locate the following PostgreSQL host-based authentication (hba) configuration file on the remote 
PostgreSQL server instance: 

Windows: C:\Program Files\PostgreSQL\X.X\data\pg_hba.conf (where X.X is the version number) 

Linux: /var/lib/pgsql/data/pg_hba.conf 

2. Add the IP address of your local JasperReports Server installation machine to this file. For example, to 
allow the local installation machine with address 192.168.12.10 to connect to the PostgreSQL server, add 
this entry to the pg hha.conf file: 

host all 192.168.12.10/32 trust 

3. Allow TCP/IP connections to the remote PostgreSQL server instance by making the following change to the 
postgresql.conf file on the remote machine: 

From: listen_addresses = 'localhost' 

To: listen_addresses = '*' 

4. Restart PostgreSQL. 

5. Using your local PostgreSQL client tools, verify that you can connect to the target remote PostgreSQL from 
the local installation machine, as described in 2.2.4.3, “Using an Existing PostgreSQL on a Remote Host,” 
on page 15. 

2.2.5 Selecting a Chrome/Chromium Configuration 

Chrome/Chromium executes JavaScript when generating graphical reports that are ran in the background or 
scheduled. (When ran directly in the web UI, the browser itself renders the graphics.) You have three options: 

• Use an existing Chrome/Chromium 

• Download Chrome/Chromium 

• Install without Chrome/Chromium 

2.2.5.1 Using an Existing Chrome/Chromium 

If you choose to use an existing Chrome/Chromium executable, you'll be prompted for the location of 
Chrome/Chromium. If Chrome/Chromium is installed at the default location, installer will detect the path, or 
you can select another location. 

The installer first checks for Chrome at the default location, if Chrome is not available, it checks for Chromium 
at the default location. 

HJi Auto-detection only works for Chrome/Chromium. A different path can be specified only for 
Chrome/Chromium in the installer. To use another browser, such as Edge, set the path in the 
js.config.properties file. 

For information about configuring Chrome/Chromium or another browser in JasperReports Server, see the 
JasperReports Server Community Project Administrator Guide. 
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2.2.5.2 Downloading Chrome/Chromium 

If you do not have Chrome/Chromium installed, you can download Chrome or Chromium during installation. 
Installer provides the Chrome and Chromium download links. 

For information about configuring Chrome/Chromium in JasperReports Server, see the JasperReports Server 
Community Project Administrator Guide. 

2.2.5.3 Installing without Chrome/Chromium 

If you choose to continue the installation without Chrome/Chromium, reports cannot be exported to PDF, 
DOCX, and other output formats. 


2.3 Choosing Sample Data 

During installation, you'll be prompted to install sample databases and sample reports. We provide these 
resources to help you evaluate the many features of JasperReports Server. This sample data includes: 

• SugaiCRM data that simulates three years of operations for a fictitious company that relies on the 
SugarCRM open source application. 

• Foodmart data that simulates three years of operations for a fictitious company. 

• JasperReports Server repository resources that use this data, such as reports, data sources, and input controls. 
Our documentation provides tutorials that use this sample data. We strongly recommend that you install it. 


2.4 Installation 

2.4.1 Installing in GUI Mode 

When you ran the installer in GUI mode, the installer presents panels that you can use to choose the installation 

environment and customize your installation. 

Steps for all installations: 

1. Rim the installer executable. On Windows, make sure to right-click the binary installer file and select Run 

as administrator from the context menu. 

• On Microsoft Windows: TIB_j s-jrs-cp_7.8.0_win_x86_64. exe 

• On Unix: TIB_js-jrs-cp_7.8.0_linux_x86_64.run 

• On Mac OS: TIB_js-jrs-cp_7.8.0_macosx_x86_64 . zip 

2. On the welcome screen, click Next. 

3. To accept the license agreement, click I accept the agreement then click Next. 

4. Select the installation type you want, then click Next. 

• Install All Components and Samples installs all components and samples. 

• Custom Install lets you choose some pre-installed and some bundled components. Make sure you 
have installed supported versions of the components you want. If you are using a pre-installed Tomcat, 
make sure it is stopped. If you are using an existing PostgreSQL instance, it must be running during 
install. See the JasperReports Server Supported Platforms Datasheet for information about supported 
versions. 
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5. Select an installation path, then click Next. The default <js-install> directory depends on your operating 
system: 

W indows: C :\Jaspersoft\j asperreport s-server-cp-7.8.0 

Linux: <U SER_HOME>/j asperreports-server-cp-7.8.0 

Linux (as root) /opt/jasperreports-server-cp-7.8.0 
Mac OSX /Applications/j asperreports-server-cp-7.8.0 


(3 


On Linux, choose a <js-install> path that’s no more than 84 characters. 


6. In the Chromium folder window, choose whether or not to use Chromium, then click Next. 

• Yes 

• No 


& 


JasperReports Server uses the Chromium browser engine when you export reports to PDF and other 
formats. If you do not have Chrome/Chromium installed, you can download Chrome or Chromium using 
the links given on the Chromium folder window. 


7. If you choose Yes, specify the Chromium binary you want to use. If Chrome/Chromium is installed at the 
default location, installer will detect the path, or click Browse to select another location. 

Auto-detection only works for Chrome/Chromium. A different path can be specified only for 
Chrome/Chromium in the installer. To use another browser, such as Edge, set the path in the 
js.config.properties file. 


r 5? For information about configuring Chrome/Chromium or another browser in JasperReports Server, see 
the JasperReports Server Community Project Administrator Guide. 

8. If you choose No, a warning message displays. Click Yes to continue. 


/B^ If you choose to continue the installation without Chrome/Chromium, reports cannot be exported to PDF, 
DOCX, and other output formats. 

If you chose Install All Components and Samples, installation begins. 

Additional steps for custom install: 

9. If you selected Custom Install, choose your components: 

• Select the bundled or an existing Tomcat, then click Next. 

• Select the bundled or an existing PostgreSQL database, then click Next. If you select an existing 
database, a warning popup will appear. Click Yes to continue. 

10. Enter your Tomcat ports, which may include server port, shutdown port, and AJP port. Then click Next. 

11. Enter your database server port and click Next. 

12. If you selected an existing Tomcat, specify your Tomcat directory and click Next. 

13. If you selected an existing PostgreSQL, specify your PostgreSQL directory and click Next. 

14. When you are prompted, choose whether or not to install sample databases and reports. Then click Next. 

15. Click Next to begin the installation. 

JasperReports Server and any selected bundled components are installed on your system. 
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Finalizing the installation: 

16. Make your post-install selections on the final screen: 

• Launch JasperReports Server Login Page - If you selected both bundled Tomcat and PostgreSQL, 
you will see an option Launch JasperReports Server Login Page. If you’re installing on Linux, 
don't close the terminal window running the start script. 

If you choose not to Launch JasperReports Server Now, the bundled components won't be started. 
If you have only one bundled component, it won't be started unless you use the Start/Stop menus or 
scripts. 

• Opt-in for JasperServer Heartbeat - Sends anonymous system and version information to Jaspersoft 
using HTTPS. 

17. Click Finish to complete the installation process, and close the installer window. 


2.4.2 Installing Using the Command Line 

In Linux, the installer is a run file; you can ran it from the command line or from a graphical environment. To 
start the installer from the command line, open a bash shell, and enter the name of the installer file. For example: 

»/TIB_j s-jrs_7.8.0_linux_x8 6_64.run 

Whether you ran the installer from the command line or in a graphical environment, you'll be prompted for the 
same information. If you're installing from the command line, use your keyboard to specify your answers. For 
example, with the license text, instead of clicking I accept the agreement, press Y and press Enter. 


2.5 Post-Installation Tasks 
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Installing JasperReports Server automatically generates encryption keys that reside on the file system. 
These keys are stored in a dedicated TIBCO Jaspersoft keystore. Make sure this keystore is properly 
secured and backed up, as described in the TIBCO JasperReports Server Security Guide. 


2.5.1 Updates Made by the Installer During Installation 

This section lists the standard updates the installer makes to your local environment when you install. When the 
installation completes, you can check whether the updates, or corresponding changes, were successful. 


Updates made to the application server: 

If you installed to an existing Tomcat, the installer attempted to make updates to the Tomcat environment, as 
shown in the following table. 


File or Directory 

Updates 

Windows: bin/setclasspath.bat 

Linux and Mac OSX: 
bin/setclasspath.sh 

Modifies JAVA_OPTS to add -Djs.license.directory. 

(Commercial installer only) 

All platforms: lib 

Adds PostgreSQL JDBC drivers to this directory. 
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Updates made to the PostgreSQL database: 

If you installed to an existing PostgreSQL database, the installer created new schemas and users in your 
database instance: 


PostgreSQL Updates 

Description 

Database jasperserver created 

This is the JasperReports Server repository database. This database 
holds all of system information, such as users, roles, data sources, 
and report definitions. 

Database user jasperdb created 

The JasperReports Server application uses this user to connect to 
the database. 

Sample database foodmart created 

(optional) Database created if install sample data option was chosen. 

Sample database sugarcrm created 

(optional) Database created if install sample data option was chosen. 


2.5.2 Installer Log File 

The installer creates a log during installation that records information as the installation progresses. If you 
encounter problems during installation, ensure that your system meets all prerequisites, and then check the 
installer log for potential problems. 

The installer log file captures information such as: 

• Environment details such as the user that invoked the installer, host name, operating system details, and so 
on 

• List of assemblies installed 

• Information related to the Ant scripts executed by the installer 
You can find the installer log at <js-install>/installation.log. 


2.5.3 Setting your Java JVM Options 

You need to set your Java JVM options. There are number of files where you can do this; refer to 4.1, “Setting 
JVM Options for Application Servers,” on page 39. 


2.6 Starting and Stopping the Server 

• Start/Stop Menu — Windows 

• Start/Stop Scripts — Linux 

• Start/Stop Apps — Mac OSX 


2.6.1 Start/Stop Menu - Windows 

This section describes start and stop procedures that vary depending on whether you installed the bundled 
Tomcat and PostgreSQL or used your own Tomcat and PostgreSQL. 
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2.6.1.1 Start/Stop Menus - Bundled Tomcat and PostgreSQL 

If you installed the bundled Tomcat and PostgreSQL, use the Windows Start menu to start and stop 
JasperReports Server. 

• Click Start > All Programs >JasperReports Server> Start or Stop Services then select Start Service 
or Stop Service. 

2.6.1.2 Additional Information about the Bundled Tomcat and PostgreSQL 

The Windows installer installs PostgreSQL and Tomcat as Windows Services. You can manage these Services in 
the Windows Control Panel: 

Control Panel > System and Security > Administrative Tools > Services 

You can also start JasperReports Server from the Windows Start menu or by using the Desktop icon. You can 
shut down using the Desktop icon. 

JasperReports Server Windows Service Names: 

PostgreSQL and Tomcat, installed as Windows Services, are listed in the Windows Services Panel as: 

• jasperreportsPostgreSQL 

• jasperreportsTomcat 

Preventing JasperReports Server from starting up automatically: 

By deiault, the bundled services start automatically on a reboot, which also starts JasperReports Server. To 
change the startup mode for the services from automatic to manual: 

• In the Windows Services Panel, select jasperreportsTomcat 

• Right-click the jasperreportsTomcat service, and select properties 

• Change the Startup type drop-down setting from Automatic to Manual 

• Do the same for the jasperreportsPostgreSQL service 

To Start JasperReports Server from the Windows Services Panel: 

• Open the Windows Services Panel 

• Select jasperreportsPostgreSQL, click Start 

• Select jasperreportsTomcat, click Start 

To Start JasperReports Server from the CMD Shell: 

• Open a Windows CMD Shell 

• Navigate to the root of the <js-install> folder (C:\Jaspersoft\jasperreports-server-cp-7.8.0) 

• servicerun START 

• servicerun STOP (to shutdown JasperReports Server) 

Running Processes: 

When JasperReports Server is running, the Windows Task Manager lists information about the processes 
running under the SYSTEM user name, for example: 

• postgres.exe 

• tomcat9.exe 
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2.6.1.3 Start/Stop Scripts - No Bundled Applications 

During installation, if you chose to install one bundled and one existing Tomcat or PostgreSQL, you can use 
the Windows start/stop scripts to start and stop only the bundled one. 

For example, if you have an existing Tomcat and you install the bundled PostgreSQL, the scripts and menus 
specified in the previous section would start and stop the PostgreSQL application. To start and stop the existing 
Tomcat, you would use the management scripts provided by the Tomcat application. 


& 


JasperReports Server requires database and application servers to be started in this order: 

1. Database server. 

2. Application server. 


2.6.2 Start/Stop Scripts - Linux 

This section describes start and stop procedures that vary depending on whether you installed the bundled 
Tomcat and PostgreSQL or used your own Tomcat and PostgreSQL. 

2.6.2.1 Manual Start/Stop 

You typically start and stop JasperReports Server at the Linux command line. Run the following commands in a 
Linux shell. 

Start JasperReports Server: 
cd <js-install> 

./ctlscript.sh start 
Stop JasperReports Server: 
cd <js-install> 

./ctlscript.sh stop 
To start and stop individual components: 
cd <js-’i.nstall> 

./ctlscript.sh start|stop postgresql 
./ctlscript.sh start|stop tomcat 

2.6.2.2 Auto Start/Stop with Bundled Tomcat and PostgreSQL 

If you want JasperReports Server to start automatically when you reboot your Linux server, you need to install 
the JasperReports Server database and application server as services. If you have installed JasperReports Server 
using the binary installer with the bundled Tomcat and bundled PostgreSQL options, you'll find an example 
jasperserver service script in the following location: 

<j s-install>/scripts/linux/jasperserver 

Edit this script and set permissions as described in the <js-install>/scripts/linux/readme file in the same location. 
Once installed, these services start automatically when you reboot, which also starts JasperReports Server. 
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2.6.3 Start/Stop Apps - Mac OSX 

After you complete the Mac OSX installation, you typically find JasperReports Server installed in the following 
location: 

/Applications/j asperreports-server-cp-7.8.0 

When JasperReports Server is running, you can see the names of the Java and PostgreSQL processes in the 
Activity Monitor. 

To start JasperReports Server, locate this folder in Finder and double-click the following app: 
j asperServerStart .app 

To stop JasperReports Server, locate this folder in Finder and double-click the following app: 
j asperServerStop .app 

The Mac lists the following information in the Activity Monitor: 

• java 

or 

org .apache .catalina.startup .Bootstrap 

• postgres 

2.6.3.1 Start/Stop Apps - Mac Dock 

Using Finder, move the following apps into the Mac Dock to start, stop, and login to JasperReports Server: 

• j asperServerStart .app 

• j asperServerStop .app 

• jasperServerLogin.app 

2.6. 3. 2 Start/Stop JasperReports Server - Mac Terminal Shell 

To start and stop JasperReports Server using the Mac terminal shell: 

1. Open a Terminal shell (Finder > Go > Utilities > Terminal Icon). 

2. Navigate to the <js-install> folder. For instance: /Applications/jasperreports-server-cp-7.8.0 

3. To start PostgreSQL, Tomcat, and JasperReports Server, enter: 

,/ctlscript.sh start 

4. To shutdown PostgreSQL, Tomcat, and JasperReports Server, enter: 

./ctlscript.sh stop 

5. To start and stop individual components: 

cd <js-install> 

./ctlscript.sh start|stop postgresql 
./ctlscript.sh start|stop tomcat 


2.7 Logging into JasperReports Server 

To log into JasperReports Server on any operating system: 

1. Start JasperReports Server. 

2. Open a supported browser: Firefox, Internet Explorer, Chrome, or Safari. 
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3. Log into JasperReports Server by entering the startup URL in your browser’s address field. The URL 
depends upon your application server. If you installed the default, bundled Tomcat use: 

http ://<hostname>: 8080/jasperserver 

• <hostname> is the name or IP address of the computer hosting JasperReports Server. 

• 8080 is the default port number for the Apache Tomcat application server. If you used a different port 
when installing your application server, specify its port number instead of 8080. 

The login page appears. 

4. Log in using the following credentials: 


User ID 

Password 

Description 

j asperadmin 

jasperadmin 

Administrator for the default organization 


If you installed the sample data, these additional sample end-users are also created. These users are non- 
administrative users with fewer system privileges. 


User ID 

Password 

Description 

joeuser 

joeuser 

Sample end-user 

demo 

demo 

Sample end-user for the SuperMart Dashboard demonstration 




When you complete the evaluation or testing of your JasperReports Server instance, change the 
administrator password (jasperadmin) and remove any sample end-users. Leaving the default 
passwords and end-users in place weakens the security of your installation. 


To log into JasperReports Server on Windows: 

On Windows, you can launch the login page from the desktop of the JasperReports Server host computer by 
clicking Start > All Programs > JasperReports Server> JasperReports Server Login. 

To log into JasperReports Server on Mac OSX: 

On Mac OSX, you can launch the login page by going to Finder and clicking the following script: 
/Applications/<j s-install>/j asperServerLogin 

For example: /Applications/j aspeireports-server-cp-7.8,0/j asperServerLogin 
To use the Dock to log into JasperReports Server: 

From Finder, you can drag the /Applications/<js-install>/jasperServerLogin.app to the Dock to handle logging 
into JasperReports Server using your default system browser. 


.8 Uninstalling the Server 

If you install JasperReports Server using the installer executable, you can uninstall it programmatically. 
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2.8.1 Windows 

To uninstall JasperReports Server on Windows 10: 

Click Start > TIBCO > JasperReports Server > Uninstall. 

2.8.2 Linux 

On Linux, the <js-install> folder includes an executable that removes JasperReports Server from the host. 

To uninstall JasperReports Server: 

1. From the command line, log in as any user with sufficient privileges. 

2. Enter the following commands: 

cd <j s~insta.l:J> 

,/uninstall 

3. Respond Y or yes to the prompt that asks if you want to remove JasperReports Server from this computer. 

2.8.3 Mac OSX 

To use Finder to uninstall JasperReports Server: 

1. Navigate to the <js-install> folder. 

2. Click the uninstall.app to launch the uninstaller. 

2.8.4 Uninstall Survey 

After running the uninstaller, you're prompted to take an uninstall survey from Jaspersoft. Survey answers are 
anonymous and help us improve our products. When you click Yes, the survey launches on the Jaspersoft web 
site in a new browser window. Select all the reasons that led you to uninstall JasperReports Server. If none of 
the reasons apply, enter a short explanation. Thank you for your feedback. 
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For production environments, use the stand-alone WAR file distribution to install the JasperReports Server 
application. Download the WAR file distribution from the Jaspersoft community site 
(http://community.jaspersoft.com) . 

The WAR file distribution contains the JasperReports Server web archive file and the scripts to create and load 
the database. 

This chapter describes how to install the WAR file on the Apache Tomcat and JBossEAP/Wildfly application 
servers. For a list of supported JDK/JVMs, application servers, databases, operating systems, and browsers, refer 
to the JasperReports Server Supported Platform Datasheet, s 
This chapter contains the following sections: 

• WAR File Distribution 

• Applications Supported by the WAR File Distribution 

• Installing the WAR File Using js-install Scripts 

• Starting the Server 

• Logging into the Server 

• Troubleshooting Your Server Configuration 

• Installing the WAR File Manually 


3.1 WAR File Distribution 

The WAR file distribution comes in a file named TIB J s-j rs-cp_7.8 .O bin .zip in compressed ZIP format. 

The WAR file distribution includes js-install shell scripts (for Linux and Windows) that automate much of 
the installation using a single properties file. These scripts are: 

• js-install-ce.bat 

• js-install-ce.sh 

The main contents of the WAR file binary distribution are shown in the following table. 
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Content Item 

Description 

JasperReports Server js-install 
Scripts 

Found at <js-install>/buildomatic/js-install-ce.batand js-install-ce.sh. 

JasperReports Server Database 
Scripts 

SQL scripts for each supported database. 

JasperReports Server 

Documentation 

Guides for end users and administrators. 

JasperReports Server Extra 

Samples 

Web Service example applications, sample reports, custom data source 
examples, and other sample files. 

JasperReports Server Standard 
Sample Data 

Sample data that highlights JasperReports Server features. 

JasperReports Server WAR file 
archive 

All of the JasperReports Server class files and dependent jars. 


The application server should reside on the local machine, but the target database can be on a remote server. 
Using a remote PostgreSQL database on some Linux platforms requires a change to its configuration file, as 
described in 2.2.4.4, “Enabling Connections to a Remote Host,” on page 16. 

3.1.0.1 About Bundled Apache Ant 

The War File Distribution ZIP includes Apache Ant version 1.9.4. The buildomatic Ant scripts come with 
Windows and Linux batch scripts pre-configured to use the bundled version of Apache Ant. You call the 
buildomatic Ant scripts from the command line in the following manner: 

Windows: js-ant <target-name> 

Linux and Mac OSX: ./js-ant <target-name> 

If you want to ran your own version of Ant, version 1.8.1 or higher is required. 

The bundled Apache Ant has an additional jar (ant-contrib.jar) that enables conditional logic in Ant. If you're 
running your own Ant, copy this jar to your Ant/lib folder. 
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On Linux and Solaris, the js-ant commands may not be compatible with all shells. If you have errors, use 
the bash shell explicitly. For more information, see A.4, “Bash Shell for Solaris, IBM AIX, HP UX and 
FreeBSD,” on page 53. 
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3.2 Applications Supported by the WAR File Distribution 

3.2.1 Database and Application Server Support 

The instructions in this and subsequent chapters support the following configurations. 


Database 

Application Server 

Instructions Located In 

PostgreSQL 

MySQL 

Apache Tomcat 
JBossEAP/Wildfly 

This chapter. 


Jaspersoft recommends that you use Apache Tomcat with PostgreSQL as your repository, unless you have a 
strong reason to use another configuration. For version information about JVMs, application servers, databases, 
operating systems, and browsers, refer to the JasperReports Server Supported Platform Datasheet. 


3.2.2 Operating System Support for Bash Shell 

JasperReports Server is a Java Web Application. Therefore, it supports all operating system platforms where Java 
is fully supported. However, for the js-install shell scripts (described in the section below), the default shell 
required is the bash shell. Here is a list of shells required: 


Operating System 

Required Shell for js-install 
scripts 

System Default Shell 

Script to Run 

Windows 

CMD shell 

CMD shell 

js-install-ce.bat 

Linux 

Bash shell 

Bash shell 

js-install-ce.sh 

Solaris 

Bash shell 

Korn shell (ksh) 

js-install-ce.sh 

IBM AIX 

Bash shell 

Korn shell (ksh) 

js-install-ce.sh 

HP UX 

Bash shell 

Posix shell (posix/sh) 

js-install-ce.sh 

FreeBSD 

Bash shell 

C shell (tcsh) 

js-install-ce.sh 


3.3 Installing the WAR File Using js-install Scripts 

Follow this procedure to install JasperReports Server using the WAR file distribution. The js-install shell scripts, 
supported on Windows, Linux, and Mac, do most of the work for you. 

Prerequisites for installing the WAR file: 

1. Install a supported version of the Java Development kit (JDK). See the TIBCO Jaspersoft Supported 
Platforms Datasheet document on the Documentation section of the Jaspersoft Community website for a 
list. 

2. Create and set the java_home system environment variable to point to the Java JDK location. 
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3. Locate or install one of the following application servers. See the TIBCO Jaspersoft Platform Support 
Guide for supported versions: 

• Apache Tomcat 

• JBoss EAP or Wildfly 

4. Locate or install the PostgreSQL or MySQL database. 


a 


The target database can be on a remote server. The application server should reside on the local 
machine. 


For an optional pre-install validation test, ran js-install-ce.bat/sh test. See 3.8.3.1, “js-install Script 
Test Mode,” on page 34 for more information. 

To install the WAR file using js-install scripts: 

The scripts are intended for the bash shell. 


If installing to non-Linux Unix platforms such as IBM AIX, FreeBSD, or Solaris, the bash shell is required 
for using the js-install scripts. 


1. Extract all files from TlB_js-jrs-cp_7.8.0_bin.zip. Choose a destination, such as C:\Jaspersoft on 
Windows, /home/<user> on Linux, or /Users/<user> on Mac. 

The directory, TlB_js-jrs-cp_7.8.0_bin, appears in the file location you choose. 

2. Copy the <dbType>_master .properties file for your database from sample_conf and paste it to 
buildomatic: 

• Copy from — <j s-install>/buildomatic/sample_conf/ 

• Paste to — <js-install>/buildomatic 

For example, if your database is PostgreSQL, copy postgresql_master .properties to <js- 
install>/buildomatic. 

3. Rename the file you copied to default_master .properties. 

4. Edit the default_master.properties file to add the settings for your database and application server. 
Table 3-1 lists sample property values for each supported database. 


Table 3-1 Sample Values for the default_master.properties File 


Database 

Sample Property Values 

PostgreSQL 

appServerType=tomcat [jboss-eap-7, wildfly, skipAppServerCheck] 
appServerDir=c:\\Program FilesWApache Software Foundation!\Tomcat 9.0 

dbHost=localhost 

dbUsername=postgres 

dbPassword=postgres 

MySQL 

appServerType=tomcat [jboss-eap-7, wildfly, skipAppServerCheck] 
appServerDir=c:\\Program FilesWApache Software Foundation!\Tomcat 9.0 

dbUsemame=root 

dbPassword=password 

dbHost=localhost 
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Note the following: 


When the property appServerType is set to skipAppServerCheck, buildomatic skips any application 
server validation. 


Backslashes in paths must be doubled in properties files, for example: 
appServerDir=C:\\Apache Software Foundation\\Tomcat9.0. 
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On Linux, if Tomcat is installed using apt-get, yum, or rpm, see A.9.4, “Tomcat Installed Using apt- 
get/yum,” on page 60. 


5. Run the js-install scripts: 

a. Start your database server. 

b. Stop your application server. 

c. Open Command Prompt as Administrator on Windows or open a terminal window on Linux and Mac 
OSX. 

d. Run the js-install script for the version and files you want, as shown in the following table. 


Commands 

Description 

cd <js-install>/buildomatic 


js-install-ce.bat (Windows) 

./js-install-ce.sh (Linux and Mac OSX) 

Installs JasperReports Server, sample data, 
and sample databases (foodmartand 
sugarcrm) 

js-install-ce.bat minimal (Windows) 

./js-install-ce.sh minimal (Linux and Mac OSX) 

Installs JasperReports Server, but not the 
sample data and sample databases 


If you encounter errors during the js-install script execution, see 3.8.3, “Error Running js-install 
Scripts (js-install-ce.bat/sh),” on page 34. 

6. Set Java JVM Options (required), as described in 4.1, “Setting JVM Options for Application Servers,” on 
page 39. 


To view the output log, look in: <js-install>/buildomatic/logs/js-install-ce-<date>. log 


3 


Installing JasperReports Server automatically generates encryption keys that reside on the file system. 
These keys are stored in a dedicated TIBCO Jaspersoft keystore. Make sure this keystore is properly 
secured and backed up, as described in the TIBCO JasperReports Server Security Guide. 


A Installing Chrome/Chromium 

You need to install and configure Chrome/Chromium to export the reports to PDF and other output formats. 

For information about configuring Chrome/Chromium in JasperReports Server, see the JasperReports Server 
Community Project Administrator Guide. 
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3.5 


Starting the Server 


To run JasperReports Server: 


Start your application server using one of these commands: 

Tomcat: Windows <tomcat>\bin\startup.bat 

Linux and Mac OSX <tomcat>/bin/startup.sh 

JBoss: Windows <jboss>\bin\standalone.bat 

Linux and Mac OSX <jboss>/bin/standalone.sh 

To view the JasperReports Server application logs, see 3.7, “Log Files,” on page 33. 


3.6 Logging into the Server 

After JasperReports Server starts up, log in by going to this URL: 

http ://<hostname>: 8080/jasperserver 
Example: 

http://localhost:8080/jasperserver 
http://jasperserver.example.com:8080/jasperserver 
The login page appears after compiling the necessary JSP files (this will take a few moments). 
Use the following credentials to log into JasperReports Server: 


User ID 

Password 

Description 

j asperadmin 

jasperadmin 

Administrator for the default organization 


If you logged in successfully, your JasperReports Server home page appears. 




When you complete the evaluation or testing of your JasperReports Server instance, change the 
administrator password (jasperadmin) and remove any sample end-users. Leaving the default 
passwords and end-users in place weakens the security of your installation. 


Refer to the TIBCO JasperReports Server User Guide to begin adding reports and other objects to the server. 


3.6.1 JasperReports Server Heartbeat 

After your initial login, you're asked to opt in to the JasperReports Server Heartbeat. The heartbeat helps 
Jaspersoft understand customer installation environments to improve our products. If you choose to enable the 
heartbeat, an HTTPS call at server startup time sends information like this to Jaspersoft: 

• Operating System and JVM type and version 

• Application Server and Database type and version 

• JasperReports Server type and version 

• Unique, anonymous identifier value 
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You can manually enable or disable the heartbeat by modifying the following property file 

jasperserver/WEB-INF/js.config.properties. To disable the heartbeat, set the heartbeat.enabled 
property to false: 

heartbeat.enabled=false 

For additional information about enabling and disabling the heartbeat component, see the JasperReports Server 
Community Project Administrator Guide. 


3.7 Log Files 

Rimtime log files contain important information about JasperReports Server operations. Depending on your 
application server, the log output goes to one of the following files. 

Tomcat: <tomcat>/webapps/jasperserver/WEB-INF/logs/jasperserver.log 

JBoss: <jboss>/standalone/deployments/jasperserver.war/WEB-INF/logs/jasperserver.log 

To view the log file, you must have access to the file system where JasperReports Server is installed. This 
section describes the settings that control the information JasperReports Server writes to its logs. 

3.7.1 Managing Log Settings 

To set the current logging levels: 

1. Log in as administrator (jasperadmin by default). 

2. Select Manage > Server Settings and choose Log Settings in the left-panel. 

3. In the Log Settings panel, use the drop-down selectors to change the log level for each class being logged. 
For more information about system logging, see the JasperReports Server Community Project Administrator 
Guide. 

3.8 Troubleshooting Your Server Configuration 

This section helps you troubleshoot the most common installation problems. 

3.8.1 Startup Problems 

If you encounter a problem trying to ran a new JasperReports Server, an incorrect database configuration is the 
likely culprit. Another common cause is a mistake in the application server configuration files. For information 
about resolving these types of errors, see Appendix A, “Troubleshooting,” on page 51. 

3.8.2 Error Running a Report 

If you have trouble running reports in your new JasperReports Server instance, see “Error Running a Report” 
in Appendix A, “Troubleshooting,” on page 51. 
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3.8.3 Error Running js-install Scripts (js-install-ce.bat/sh) 

The js-install script creates an output log that captures standard output and error output. If you encounter 
problems during the execution of the script, or if you want to remember which options you chose, open the 
output log fde. 

To troubleshoot problems running js-install scripts: 

1. Open the output log file located in: 

<js-install>/buildomatic/logs/js-install-<date>-<number>.log 

2. Try to find the first error encountered by the js-install steps. 

• Go to the end of the output log. 

• Scroll back through lines of error messages until you find the first error logged. Typically, this error 
causes more errors later in the log. 

• Finding the original error is the way to understand the problem. However, this can often be tricky 
because Java stack traces in conjunction with the Spring application component framework can make 
the error output quite long. 

3. Incorrect settings in the default_master.properties file cause most problems, which you can correct by 
editing your default_master .properties settings. Common errors are: 

• Typos in the path for the application server 

• Misspelling the hostname or password for the database 

To recreate your default_master.properties settings: 

1. Open the file <js-install>/buildomatic/default_master.properties, make corrections, and save it. 

2. Re-run the js-install script. 

The js-install script uses the current values in the default_master .properties file. 

To help isolate errors, ran the j s-install scripts in test mode. 

3.8.3.1 js-install Script Test Mode 

You can ran the js-install and js-upgrade scripts in test mode using the test option. In test mode, the 
js-install scripts check your default_master .properties settings and validate the application server 
location and connection to the specified database. Using test mode can help debug issues, such as an incorrect 
database password. Your system isn’t altered when executing the script in test mode. 

To run the js-install script in test mode on Windows: 

1. Navigate to the buildomatic directory: 

cd <js-install>/buildomatic 

2. Enter the following command to ran the js-install script in test mode: 
js-install-ce.bat test 

To run the js-install script in test mode on Linux or Mac OSX: 

1. Navigate to the buildomatic directory: 

cd <js-install>/buildomatic 

2. Enter the following command to ran the js-install script in test mode: 

./js-install-ce.sh test 
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3.8.4 Problem Connecting to a Cloud Database Instance 

A cloud database instance (such as Amazon EC2) typically disables unused IP ports. When the j s-install 
script runs, it validates the database hostname using the built-in ant operation <isreachable>. This operation 
is similar to a network ping and may cause a “hang” issue if the port is unavailable. In this case, the 
validateHost step can be commented out in the buildomatic/validation.xml file. See the comment in the 
do-pre-install-test target. 

3.8.5 Error Exporting Reports 

The export of Reports fails when Tomcat is ran as root in the JasperReports Server installation on Linux. The 
Tomcat log file displays an error, for example: 

202Q-Q6-11T17:32:19,031 ERROR SecureExceptionHandlerImpl,http-nio-8080-exec-8:lT6 - 
com.github.kklisura.cdt.launch.exceptions.ChromeProcessTimeoutException: Failed while waiting for 
chrome to start: Timeout expired! Chrome output: [0611/173218.897370:ERROR:zygote_host_impl_linux.ee 
(89)] Running as root without —no-sandbox is not supported. See https://crbug.com/638180. 

To resolve this you need to set the following property in the jasperreports.properties file: 

• net.sfjasperreports.chrome.argument.no-sandbox=true 
After setting this property, restart JasperReports Server to enable it. 

For information about configuring this property, see the JasperReports Server Community Project Administrator 
Guide. 

3.9 Installing the WAR File Manually 

You may need to install the WAR file manually when you cannot use the j s-install scripts. 

The manual huildomatic steps described in this procedure execute the same Ant targets as the j s-install 
scripts (js-install-ce.sh/.bat). The procedure shows which huildomatic targets to execute manually if you 
are unable to use the j s-install scripts. 

To install the WAR file distribution using manual buildomatic steps: 

1. Start your database server. 

2. Stop your application server. 

3. Create and edit a default_master .properties file to add the settings in for your database and 
application server as described in 3.3, “Installing the WAR File Using js-install Scripts,” on page 29. 

4. Open a Command Prompt as Administrator on Windows or open a terminal window on Linux or Mac. Run 
the following commands. 
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Table 3-2 Buildomatic Targets to Execute to Install the WAR File 


Commands 

Description 

cd <js~install>/buildomatic 

Makes the buildomatic directory your current directory. 

js-ant create-js-db 

Creates the JasperReports Server repository database. 

js-ant create-sugarcrm-db 

js-ant create-foodmart-db 

(Optional) Creates the sample databases. 

js-ant load-sugarcrm-db 

js-ant load-foodmart-db 

(Optional) Loads sample data into the sample databases. 

js-ant update-foodmart-db 

(Optional) Initializes the sample databases 

js-ant init-js-db-ce 

js-ant import-minimal-ce 

Initializes the jasperserver database, loads core 
application data. Running js-ant import-minimal-ce is 
mandatory. The server cannot function without this data. 

js-ant import-sample-data-ce 

(Optional) Loads the demos that use the sample data. 

js-ant deploy-webapp-ce 

Configures and deploys the WAR file to Tomcat or JBoss. 


HJi On non-Linux Unix platforms, the js-ant commands may not be compatible with all shells. If you have 
errors, use the bash shell explicitly. For more information, see A.4, “Bash Shell for Solaris, IBM AIX, 
HP UX and FreeBSD,” on page 53. 

If you encounter an error when running create-sugarcrm-db, create-foodmart-db, or create-js-db, 

you can create the JasperReports Server database manually using the database administration tool for your 
particular database type. To create the JasperReports Server database manually for PostgreSQL or MySQL, 
see Appendix B, “Manually Creating the JasperReports Server Database,” on page 65. 

If you have previously installed the databases, you can drop the old versions and then recreate the 
databases. To do this, ran the following drop commands before running the commands in Table 3-3 


Table 3-3 Buildomatic Targets to Execute to Delete Sample Databases 


Commands 

Description 

js-ant drop-sugarcrm-db 

js-ant drop-foodmart-db 

(Optional) Deletes the sample databases. 

js-ant drop-js-db 

(WARNING) This will delete the JasperReports Server 
repository database. Only run this command if you intend 
to recreate the jasperserver database 


5. Set Java JVM Options (required) as described in 4.1, “Setting JVM Options for Application Servers,” on 
page 39. 
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3 


Installing JasperReports Server automatically generates encryption keys that reside on the file system. 
These keys are stored in a dedicated TIBCO Jaspersoft keystore. Make sure this keystore is properly 
secured and backed up, as described in the TIBCO JasperReports Server Security Guide. 
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This chapter contains the following sections: 

• Setting JVM Options for Application Servers 

• Working With JDBC Drivers 

• Locating and Changing Buildomatic Configuration Files 

• Configuring Report Scheduling 

• Updating XML/A Connection Definitions 


4.1 Setting JVM Options for Application Servers 


& 


The settings in this section apply specifically to the Oracle/Sun JVM. Other JVMs may or may not have 
equivalent settings. Fora list of supported JDK/JVMs and application servers, see the TIBCO Jaspersoft 
Platform Support document. 


You may need to set the following options for your JVM: 

• Memory - Java Virtual Machine (JVM) runtime parameters normally need to be explicitly set so that the 
memory settings have values larger than the default settings. The options and values depend on your 
version of Java and the application server you use. You may need to increase the memory assigned for the 
JVM according to your usage. 

• Garbage collection - You may need to tune garbage collection for your JVM, depending on your memory 
and CPU usage as well as JasperReports Server throughput. Different collectors have different performance 
characteristics. Consult the documentation for your JVM for information on available collectors. 

• Date format in Java 11 - Java 11 changed the default date format to conform to CLDR 33. If you are 
running on Java 11 and want backwards compatibility with Java 8 date formatting, you need to set 

-Djava.locale.providers=COMPAT on all nodes. 


4.1.1 Tomcat and J Boss JVM Options 

The following tables present some typical settings of JVM options that affect JasperReports Server. For 
information about changing a JVM option setting for your particular environment, see your application server 
documentation. 
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JVM Options on Windows (64 bit) 

Options for 
all app 

servers 

set JAVA_OPTS=%JAVA_OPTS% -Xms2048m -Xmx4096m -Xss2m 

set JAVA_OPTS=%JAVA_OPTS% -XX:+UseConcMarkSweepGC 

Java 11 

set JAVA_OPTS=%JAVA_OPTS% -Djava.locale.providers=COMPAT 


JasperReports Server doesn’t provide a virtual X frame buffer on Linux. If your Linux applications are graphical, 
set the -Djava.awt.headless=true to prevent Java from trying to connect to an X Server for image 
processing. 


JVM Options on Linux and Mac OSX (64 bit) 

Options for 
all app 

servers 

export JAVA_OPTS-'$JAVA_OPTS -Xms2048m -Xmx4096m -Xss2m" 
export JAVA_OPTS="$JAVA_OPTS -XX:+UseConcMarkSweepGC" 

Java 11 

export JAVA_OPTS="$JAVA_OPTS -Djava.locale.providers=COMPAT" 


You can set JVM options multiple ways. Sections 4.1.2 - 4.1 present step-hy-step instructions for performing 
this task. Alternatively, you can add your java_opts settings to any of the following files. 


File 

Add JVM Options After This Line on Windows 

<tomcat>\bin\setclasspath.bat 

set JAVA_ENDORSED_DIRS=%BASEDIR%\common\endorsed 

<tomcat>\bin\setenv.bat 

javajopts setting can go anywhere in this file. 

<jboss>\bin\standalone.conf.bat 

Find the existing java_opts line, remove the default memory settings from this line, 
and add a new line with the recommended JAVA opts after this line. 

For example, you might remove the following default settings: 

-Xms64m -Xmx512m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m 

Then add the recommended settings on a new line. We recommend that you do not 
set MaxMetaspaceSize. 


File 

Add JVM Options After This Line on Linux 

<tomcat>/bin/setclasspath.sh 

JAVA_ENDORSED_DIRS="$BASEDIR"/common/endorsed 

<tomcat>/bin/setenv.sh 

JAVA_opts setting can go anywhere in this file. 
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File 

Add JVM Options After This Line on Linux 

<jboss>/bin/standalone.conf 

Find the existing java_opts line, remove the default memory settings from this line, 
and add a new line with the recommended java opts after this line. 

For example, you might remove the following default settings: 

-Xms64m -Xmx512m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m 

Then add the recommended settings on a new line. We recommend that you do not 
set MaxMetaspaceSize. 


4.1.2 Changing JVM Options for Tomcat as a Windows Service 

If you installed JasperReports Server to use Tomcat running as a Windows service, you can set Java options on 
the Java Tab of the Tomcat Properties dialog: 

1. Launch the Tomcat configuration application. If you installed the bundled Tomcat, you can do this by 
going to the <js-install>/apache-tomcat/bin directory and double-clicking the jasperreportsTomcat.exe file. 
(If you have multiple instances of JasperReports Server installed, the file name will be of the form 
jasperreportsTomcatnum<number>.exe, for example, jasperreportsTomcatnum2.exe.) If you installed Tomcat 
using an existing Windows service, look for an .exe file in the same location, with the same name as your 
Tomcat service, or select the service from the Windows Start menu: 

Start > Programs > Apache Tomcat > Configure Tomcat (Run as administrator) 

2. In the Apache Tomcat Properties dialog, click the Java tab. 

3. In the Java Options field, add your JAVA_OPTS values according to the tables above. 

Enter only the options preceded by -X or -d, not set JAVA_OPTS=%JAVA_GPTS%. 

Enter only one Java option setting per line. 

4. For instance, add options as follows: 

-Xms2048m 

-Xmx4096m 

-Xss2m 

5. Click Apply, then click ok. 

6. Stop and restart Tomcat. 

4.1.3 Changing JVM Options for Bundled Tomcat on Linux 

If you installed the bundled Tomcat, you can set Java options by editing the appropriate Tomcat configuration 
script. The steps to change JVM options are: 

1. Open the following file for editing: 

cd <j s-install>/apache-tomcat/scripts/ctl.sh 

2. Look for the start_tomcat () function and locate the JAVA_OPTS variable inside it. 
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3. Modify the java_opts values according to the tables above. For example: 

start_tomcat() { 

is_tomcat_running 

export JAVA_OPTS="-Xms2048m -Xmx4096m" 

export JAVA_OPTS="-Xss2m -XX:+UseConcMarkSweepGC" 


& 


There may be more than one occurrence ofthe Java_OPTS variable in the ctl.sh file. Make sure you edit 
the instance inside the start_tomcat () function. 


4. Save and close the ctl. sh file. 

5. Stop and restart PostgreSQL and Tomcat as described in 2.6, “Starting and Stopping the Server,” on 
page 20. 


.2 Working With JDBC Drivers 

This section describes how to set up your installation to use a driver other than the default driver. 

2.1 Open Source JDBC Drivers 

For open source JDBC drivers, buildomatic is set up to use a single default driver. If you want to use a driver 
other than the default driver, you can modify the buildomatic property files that determine the default JDBC 
driver. 

The buildomatic JDBC driver property files are set up to point to a specific driver jar. This allows for multiple 
driver jar files in the same buildomatic/conf_source/db/<dbType>/jdbc folder. During the installation 
procedure only the default driver jar is copied to your application server. 

If you want to use a newer JDBC driver version or a different JDBC driver, you can modify the buildomatic 
properties seen in your default_master .properties file. 

4.2.1.1 PostgreSQL Example 

The buildomatic/conf_source/db/postgresql/jdbc folder contains these driver files: 
postgresql-42.2.5 .jar 

For instance, to change the default driver used by PostgreSQL from type jdbc4.2 to jdbc4.1: 

1. Download postgresql-42.2.5.jre7 from https://jdbc.postgresql.org/download.html and save it under 
buildomatic/conf_source/db/postgresql/jdbc. 

2. Edit your defaultmaster.properties file, <js-install>Edit your defaultmaster.properties file, <js- 
install>/buildomatic/default_master.properties as follows: follows: 

Uncomment and change: 

# maven.jdbc.version-42'.2.5 

To: 

maven.j dbc.version42.2.5,j re7 
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When you next run a buildomatic command, such as deploy-webapp-ce, the jdbc4.1 driver will be copied to 
your application server. 

4.2.1.2 MySQL Example 

The buildomatic/conf_source/db/mysql/jdbc folder contains this driver file: 
mariadb-java-client-2.5,3.jar 

If, for instance, you want to use a JDBC driver built and distributed by the MySQL project, such as mysql- 
connector-java-8.0.20-bin. jar, you first need to download the driver from the MySQL Connector/J 
download location: 

https://dev.mysql.com/downloads/connector/j/ 

Next, change your buildomatic configuration properties to point to this new driver. 

Edit your default master.properties file: 

<j s-install>/buildomatic/default_master.properties 
Uncomment and change: 

# j dbcDriverClass=com.mysql.j dbc.Driver 

# maven.jdbc.groupId=mysql 

# maven.j dbc.artifactId=mysql-connector-java 

# maven.jdbc.version=5.1.30-bin 

To: 

jdbcDriverClass=com.mysql.jdbc.Driver 
maven.j dbc.groupId=mysql 

maven.j dbc.artifactId=mysql-connector-java 
maven.j dbc.version=5.1.30-bin 


4.2.2 Application Server Copy-to Locations 

When the deploy-webapp-ce buildomatic target is executed it copies the JDBC driver to the following default 
locations: 

Tomcat: <tomcat>/lib 

JBoss: <jboss>/standalone/deployments 

W ildfly: <wildfly>/standalone/deployments 

4.3 Locating and Changing Buildomatic Configuration Files 

The Ant-based buildomatic scripts contain support files for setting up and configuring a number of databases 

and application servers. This section describes the locations of some of these files and how to change their 
content. 

4.3.1 Regenerating Buildomatic Settings 

Whenever you change your default_master .properties file and re-run the js-install scripts (or any other 
buildomatic target), your generated configuration settings are automatically updated. The generated settings are 
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in this location: 

<js-install>/buildomatic/build_conf/default 

The settings are regenerated automatically based on the updated timestamp on the properties file. 

If you want to explicitly regenerate your configuration, ran the following buildomatic targets: 

cd <js-install>/buildomatic 
js-ant clean-canfig 
js-ant gen-config 

The first target clears the configuration template files in buildomatic/build_conf/default directory. The 
second re-builds the configuration settings. 


4.3.2 Locating Buildomatic-Generated Property Files 

After you set your database and application server property values, initiate buildomatic to automatically 
generate the database and application server configuration files needed to prepare for a JasperReports Server 
installation. 

The generated property files are in this location: 

<js-install>/buildomatic/build_conf/default 
Some of the key configuration files are: 
j s.j dbc.properties 
j s.quartz.properties 
js-jboss-ds.xml 

maven_settings. xml - (used for source code build) 

More generated property files are: 

<js-install>/buildomatic/build_conf/default/webapp 
Included in the /webapp directory are configuration files, such as: 

META-INF/context.xml 

WEB-INF/hibernate.properties 

WEB-INF/j s.quartz.properties 

These auto-generated files are removed if you ran the buildomatic target: clean-config. You can then 
regenerate the files by running the target: gen-config. (Also, after running clean-config, any subsequent 
target will regenerate the configuration files.) 


4.3.3 Buildomatic Location for JasperReports Server WAR File 

Buildomatic takes the JasperReports Server WAR file from the root of the <js-install> directory: 

<j s-install>/j asperserver.war 

When you ran the deploy-webapp-ce target, buildomatic unpacks the war archive into your application server 
and copies the needed database configuration files to their appropriate locations. For instance, in the case of 
Tomcat: 

• <js-install/> j asperserver.war 

Unpacked and copied to <tomcat>/webapps/jasperserver/* 

• <js-install>/buildomatic/build_conl7default/webapp/META-INF/context.xml 
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Copied to <tomcat>/webapps/jasperserver/META-INF/context.xml 
<js-install>/buildomatic/build_conf/default/webapp/WEB-rNF/hibemate.properties 
Copied to <tomcat>/webapps/jasperserver/WEB-INF/hibemate.properties 
<j s-install>/buildomatic/build_cont7 default/webapp/WEB-INF/j s.quartz.properties 
Copied to <tomcat>/webapps/jasperserver/WEB-INF/j s.quartz.properties 
<js-install>/buildomatic/build_conf7db/postgres/jdbc/postgresql-42.2.5.jar 
Copied to <tomcat>/lib 


4.3.4 Buildomatic Location for SQL Scripts 

Buildomatic comes with SQL scripts and other utilities that support a number of databases. These files are in: 

<js-install>/buildomatic/install_resources/sql/ 

For example, some key files are (same pattern for additional databases): 
<js-install>/buildomatic/install_resources/sql/postgresql/js-create.ddl 
<js-install>/buildomatic/install_resources/sql/postgresql/quartz.ddl 

<js-install>/buildomatic/install_resources/sql/postgresql/upgrade-postgresql-6.0.0-6.1.0-ce.sql 

<js-install>/buildomatic/install_resources/sql/postgresql/js-drop.ddl 

<js-install>/buildomatic/install_resources/sql/postgresql/drop-quartz.ddl 


& 


You can run these scripts manually by copying them to the location of your database client software. 


4.3.5 Buildomatic Location for Database Creation Scripts 

For most databases the buildomatic scripts can create the metadata repository database used by JasperReports 
Server. This is the database that stores data defining users, roles, data sources, reports, OLAP views, domains, 
and other data. This database is normally named jasperserver. 

Buildomatic attempts to create the jasperserver database via JDBC when the create-js-db target is executed. 
The scripts and property files used to create the jasperserver database are located in the following directory: 
<js-install>/buildomatic/conf_souice/db/<db_name>/sciipts.properties 


4.3.6 Buildomatic Location for Sample Data Catalog ZIP Files 

Buildomatic includes export files that hold the JasperReports Server sample data (with examples of new 
features). This sample data is loaded when you ran the buildomatic target import-sample-data-ce, for 
instance. These export files along with other important export files are located here: 

<js-install>/buildomatic/install_resources/export/ 

Here are some key files: 

js-catalog-<db_name>-minimal-ce.zip 
j s-catalog-<db_name>-ce.zip 
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4.3.7 Hibernate Properties Settings 

After you run buildomatic to generate your configuration files, your hibernate.properties settings are in the 
following directory: 

<js-install>/buildomatic/build_conf/default/webapp/WEB-INF/hibernate.properties 
Within the jasperserver WAR file the hibernate .properties file is found at the following location: 
<appserver-path>/jasperserver/WEB-INF/hibernate.properties 

The buildomatic scripts automatically create this configuration file. When you ran the buildomatic target 
deploy-webapp-ce this file is copied to JasperReports Server in your application server. 

Hibernate property values are: 

PostgieSQL: metadata .hibernate. dialect=com. j aspersoft.hibernate. dialect. PostgresqlNoBlobDialect 

MySQL 5.5: metadata. hibernate. dialect=org. hibernate. dialect.MySQL5InnoDBDialect 


4.3.8 Database Connection Configuration Files 

4.3.8.1 Tomcat 

When you've set up the buildomatic configuration for your database, the Tomcat context.xml will be 
automatically created with the appropriate settings for JasperReports Server. 

When you ran the buildomatic target deploy-webapp-ce, the context.xml will be automatically copied into 
the jasperserver WAR set of files. 

You can view the automatically generated context.xml at the following location: 

<js-install>/buildomatic/build_conf7default/webapp/META-INF/context.xml 
The final location of the context.xml is: 

<tomcat>/webapps/j asperserver/META-INF/ context.xml 
Older versions of Tomcat will create a copy of the context.xml file with a changed name that will he read 
instead of the one found in the jasperserver war file. This can be confusing for Tomcat users who try to change 
their database settings. If you change your settings, delete the file in this location: 
<tomcat>/conf7Catalina/localhost/jasperserver.xml 

4.3.8.2 JBoss 

When you've set up the buildomatic configuration for your database, the JBoss data source definition file will 
be automatically created with the appropriate settings for JasperReports Server. 

When you ran the buildomatic target deploy-webapp-ce, the js-jboss-ds.xml will be automatically copied into 
the JBoss instance. 

You can view the automatically generated js-jboss-ds.xml at the following location: 

<j s-install>/buildomatic/build_conf7 default/j s-jboss-ds.xml 
The final location of the js-jboss-ds.xml is: 

<jboss>/standalone/deployments/jasperserver.war/WEB-INF/js-jboss7-ds.xml 
When JasperReports Server is running under JBoss, a couple of INFO log messages and an XML/A connection 
error may occur depending on the version of JBoss you're running. 

For more information, refer to troubleshooting section A.9.5, “JBoss Modifications,” on page 61. 
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4.4 Configuring Report Scheduling 

The JasperReports Server report scheduling feature is powered by the Quartz scheduler tool. Buildomatic 
automatically handles configuration settings for Quartz-based report scheduling. 

In a deployed JasperReports Server instance, you'll find the js.quartz.properties file in this location: 

<app-server-path>/jasperserver/WEB-INF/js.quartz.properties 
For mail server configuration, you'll find an additional property setting for authentication in this file: 

<app-server-path>/webapps/jasperserver/WEB-INF/applicationContext-report-scheduling.xml 
The following configurations are discussed in this section: 

• Mail Server Configuration 

• Quartz Driver Delegate Class 

• Report Scheduler Web URI 

• Quartz Table Prefix 

• Settings for import-export 

• Setting Properties in the default master.properties File 


4.4.1 Mail Server Configuration Settings 

You can specify email addresses to notify when a report completes. To do this, configure JasperReports Server 
to contact an email server as shown in the following table. 


Configuration File 

<app-server>/<deployment>/WEB-INF/js.quartz. properties 

Property 

Description 

report.scheduler.mail.sender.host 

The name of the computer hosting the mail server 

report.scheduler.mail.sender.username 

The name of the mail server user JasperReports 

Server can use 

report.scheduler.mail.sender.password 

The password of the mail server user 

report.scheduler.mail.sender.from 

The address for in the From field on email 

notifications 

report.scheduler.mail.sender.protocol 

The protocol that the mail server uses. JasperReports 
Server supports only SMTP. 

Note: Your entry must be lower case (smtp) 

report.scheduler.mail.sender.port 

The port number the mail server uses. The default is 
typically 25 (other ports may not work in earlier 
JasperReports Server versions). 
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Configuration File 

<app-server>/<deployment>/WEB-INF/applicationContext-report-scheduling.xml 

Property 

Bean 

Description 

j avaMailProperties 
key="mail.smtp.auth" 

reportScheduler 

MailSender 

If your mail server requires authentication, change 
this property from false to true. 


4.4.2 Database Settings for the Quartz Driver Delegate Class 

Quartz uses the Quartz driver delegate class to interact with the JDBC driver. 

HQ If you used buildomatic to install JasperReports Server, the correct value of the Quartz driver delegate 
class is automatically set for your database. 

If you didn’t use buildomatic to install JasperReports Server, refer to the following table to edit the 

js. quartz .properties file and set the value of the Quartz driver delegate class to the correct value for your 

database. 


Configuration File 

<app-server>/<deployment>/WEB-INF/js.quartz. properties 

Property 

Database 

Value 

quartz.delegateClass 

MySQL 

org.quartz.impl.jdbcjobstore.StdJDBCDelegate 

PostgreSQL 

org.quartz.impl.jdbcj obstore.PostgreSQLDelegate 


4.4.3 Settings for the Report Scheduler Web URI 

JasperReports Server uses the Report Scheduler Web URI to construct the link it sends in the output of a 
scheduled job. This link must be correct for the user to access the report on the server. 

The port on which you ran JasperReports Server and the context root of the deployed JasperReports Server web 
application determine the report scheduler Web URI. The default context root is jasperserver. 

To set this value manually, edit this file: 

<app-server>/<deployment>/WEB-INF/js.quartz.properties. 

Change the properties as shown in the following table. 


Property 

App Server 

Example Value 

report.scheduler.web.deployment.uri 

Apache Tomcat 

http://localhost:8080/jasperserver 

JBoss 

http://localhost:8080/jasperserver 
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4.4.4 Settings for the Quartz Table Prefix 

For databases that support schemas, you can set the Quartz table prefix to include the schema, if you use one. 


& 


If you installed JasperReports Server using buildomatic the Quartz table prefix is set automatically. 


To set this value, edit the file <app-server>/<deployment>/WEB-lNF/js.quartz.properties. Change the 
following property: 


Property 

Description 

quartz.tablePrefix 

The prefix for the quartz table, including any schema name. 


4.4.5 Settings for Import-Export 

If you manually configure the import-export shell scripts instead of using the buildomatic, make sure your 
settings for the Quartz driver delegate class property are correct for your database. 


a 


If you install using buildomatic, these settings are handled automatically (in buildomatic import-export). 


To configure the import-export scripts manually, edit this file: 

<j s-install>/buildomatic/conf_source/ieCE/j s.quartz.properties 

Change the following properties: 


Property 

Description 

quartz.delegateClass 

Set to the same value as described in 4.4.2, “Database 

Settings for the Quartz Driver Delegate Class,” on page 48. 

quartz.tablePrefix 

Set to the same value as described in 4.4.4, “Settings for the 
Quartz Table Prefix,” on page 49 


4.4.6 Setting Properties in the default_master.properties File 

You can modify the default_master.properties file to configure JasperReports Server functionality. 
Uncomment the properties you want to have them take effect upon installation. The properties are documented 
directly in the default_master .properties file: 

<j s-install>/buildomatic/default_master.properties 
You'll find a sample master.properties here (in the case of PostgreSQL): 

<js-install>/buildomatic/sample_conf/postgresql_master.properties 

When you execute the js-install-ce.sh/bat script (or the underlying deploy-webapp-ce ant target), these 
properties will be set in the deployed JasperReports Server in the j s. quartz .properties file. 
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4.4. 6.1 Report Scheduler Email Properties 

You can set the following properties to configure the Report Scheduler email (default values are shown): 

quartz.mail.sender.host=mail.localhost.com 

quartz.mail.sender,port=25 

quartz.mail.sender.protocol=smtp 

quartz.mail.sender.username=admin 

quartz.mail.sender,password=password 

quartz.mail.sender.from=admin@localhost.com 

quartz.web.deployment.uri=http://localhost:8080/jasperserver 

4.4.6.2 Diagnostic Properties 

The following properties configure the Diagnostic functionality: 

diagnostic.jmx.usePlatformServer = false 
diagnostic.jmx.port = 10990 
diagnostic.jmx.name = jasperserver 
diagnostic.jmx.rmiHost = localhost 

Look at the descriptions of the properties in the defaultmaster.properties file and also refer to the JasperReports 
Server Community Project Administrator Guide for more information on these settings. 


.5 Updating XML/A Connection Definitions 

Sample XML/A connections are included with the JasperReports Server sample data. If you plan to use XML/A 
Web Services in your environment, you may want to update the hard coded values in the sample connections. 
If you have Jaspersoft OLAP enabled (via your license), JasperReports Server can make XML/A connections 
over the Web Services interface. These connections need a user account for authentication. You may have 
different usernames and passwords than the defaults in the sample data. Additionally, your application server 
hostnames and port may be different than the default values. In such cases, the connections and resources that 
rely on them will fail. 

The sample connections are: 

• Foodmart Sample XML/A connection 

• SugaiCRM Sample XML/A connection 
To validate and update these resources: 

1 . Log into JasperReports Server as an administrator (like j asperadmin). 

2. Navigate to the Repository Management page (View> Repository). 

3. Click to expand the Analysis Components folder, then the Analysis Connections folder. Click to highlight 

Foodmart XML/A Connection, then click Edit. 

4. Edit the following fields: 

• URI (hostname and port) 

• Login Username 

• Login Password 

5. Click Next, then Save. 

6. Make the same updates for SugarCRM XML/A Connection. 
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This appendix contains the following sections: 

• Binary Installer Freezes 

• Error Running Buildomatic Scripts 

• Unable to Edit Files on Windows 10 

• Bash Shell for Solaris, IBM AIX, HP UX and FreeBSD 

• Linux Issues 

• Installation Error with Windows Path 

• Mac OSX Issues 

• Database-related Problems 

• Application Server-related Problems 

• Problems Importing and Exporting Data from the Repository 


A.1 Binary Installer Freezes 

If you run the JasperReports Server installer on any platform and the installation foils, the following resources 
can help you find the source of the error. 

A. 1.1 Installer Log Files 

If you get an error when running the JasperReports Server installer on any platform, look at the log file created 
by the installer. This log records the status and completion of installer operations. If a specific error occurred, 
you may find an explicit error message. Even without an explicit error message, the log file should help you 
locate the cause of the error. 

You'll find the installer log for your platform in the following location: 

Windows: s_ instaii>/instailation.log 
Linux: <js-install>/installation.log 

Mac <j s-installVinstallation.log 

If you've tried multiple installs, make sure you view the most recent install log. 
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A.2 Error Running Buildomatic Scripts 

The buildomatic scripts depend on both Java and Apache Ant. Two common configuration errors are possible 
when attempting an installation using these scripts (if you're not using the included, bundled Apache Ant). 

A.2.1 Missing Java JDK 

If you have the Java JRE (Java Runtime Environment) instead of the JDK, you won't have all the required 
utilities. In particular, you may see an error referring to the tools)ar, as in the following message: 

[exec] [ERROR] BUILD FAILURE 

[exec] [INFO] - 

[exec] [INFO] Compilation failure 

[exec] Unable to locate the Javac Compiler in: 

[exec] c:\Program Files!Java\jdkx.x.x_xx\jre\..\lib\tools.jar 

[exec] Please ensure you are using JDK x.x or above and 

[exec] not a JRE (the com.sun.tools.javac.Main class is required). 

[exec] In most cases you can change the location of your Java 
[exec] installation by setting the JAVA_HOME environment variable. 

The solution is to download and install the Sun Java JDK, labeled as the Java SE Development Kit on the 
Oracle web site. 


A.2.2 Forgot to Copy the File ant-contrib.jar 

If you're using your own version of Ant and your Ant instance doesn't have the ant-contrib.jar in the lib 
directory, you'll get an error similar to the following: 

BUILD FAILED 

e:\j s-builds!jasperserver\buildomatic\iostall.xml:6: 

Ant failed to create a task or type. To correct the error, copy <js-install>/buildomatic/extra-jars/ant-contrib.jar to 
your <apache-ant>/lib directory. 

A.2.3 Failure with '$' Character in Passwords in Buildomatic Scripts 

If your password in buildomatic scripts includes two of more '$' characters in a row, Ant will not accept it. This 
issue does not occur when dollar signs are separated by other characters. For example, $pas$word$ or 
pas$word$ will not fail. 

If you have two consecutive dollar signs, you'll need to escape each with three more dollar signs. For example, 
if your password is pa$$word, enter it as pa$$$$$$$$word in the configuration file. Once you do this, 
JasperReports Server will set all data connections to pa$$word. 

A.2.4 Older Apache Ant Version 

We recommend Apache Ant version 1.9.4 or later. The earliest compatible version is Ant 1.8.1. 
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Older versions of Ant will cause an error similar to the following: 

BUILD FAILED 

c:\j s-builds\j asperserver\buildomatic\install.xml:37: 

Problem: failed to create task or type componentdef 

To check your version of Ant and verify that it's at a high enough level, enter: 

ant -version 

If you have a earlier version of Ant, check to see if it's set in your class path by entering: 

echo $CLASSPATH 

To use the JasperReports Server version of Ant, update your classpath variable to point to the <js- 
install>/apache-ant/bin directory. 


3 Unable to Edit Files on Windows 10 

In some cases, you may want to manually edit files in your C:/Jaspersoft directory during or after installation. 
For security reasons, Windows 10 doesn't allow normal processes to change files in many folders including the 
Program Files folder, for instance. When you attempt to edit these files, you may see an error like this: 

You don't have permission to save in this location. Contact the administrator to obtain permission. 

You can edit these files by running as administrator. For example, to edit these files with Notepad on Windows 
10: 

Click Start and find the Notepad application. Right-click Notepad, and click Run as administrator. 


4 Bash Shell for Solaris, IBM AIX, HP UX and FreeBSD 

The bash shell is required to execute the js-install shell scripts described in Chapter 3, “Installing the 
WAR File Distribution,” on page 27. The following js-install and js-upgrade scripts are in the 
buildomatic folder: 

js-install-ce.sh 
js-upgrade-newdb-ce.sh 
js-upgrade-samedb-ce.sh 

The bash shell is not included by default in all Unix platforms. When the bash shell is not available, you'll need 
to download and install the bash shell specific to your platform. 

Alternatively, you can manually ran the same “buildomatic” Ant targets that are ran by the js-install script. 
These Ant targets are listed in “Troubleshooting Your Server Configuration” on page 33. 

Also, make sure you've updated your local Ant to include ant-contrib. jar, which supports conditional logic 
in Ant. Copy the ant-contrib. jar to your <ant_home>/lib folder lfom: 
buildomatic/extra-j ars/ant-contrib.j ar. 

For more information see A.2.2, “Forgot to Copy the File ant-contrib.jar,” on page 52. 
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If you try using the Ant that's included with the JasperReports Server WAR file Distribution ZIP package, you 
may get the same non-bash syntax error. You may get the error below, for example: 

js-ant help-install 

ANT_HOME=../apache-ant: is not an identifier 

If you have the bash shell installed, you can try executing the js-ant command by calling bash explicitly, for 
example: 

bash js-ant help-install 


A.5 Linux Issues 


A.5.1 File Issues with Extended Character Sets on Linux 

Your operating system configuration can influence the behavior of characters supported by JasperReports Server. 
On some Linux systems, Oracle JDK 8 sets the 'sun. jnu.encoding' system property to define the character set 
for encoding file names for I/O operations. This system property is set up on Java application startup and takes 
its value from the Linux system locale. 

However, if the operating system is configured to use a non-UTF-8 encoding, JasperReports Server components 
may function in an unexpected way. For example, log collectors with non-UTF-8 names may be configured 
incorrectly. To fix these problems on a Linux operating system, enable Unicode support by setting the lang and 
lc_all environment variables to a locale with the UTF-8 character set. This allows the operating system to 
process any character in Unicode. For example, LANG=en_US .UTF-8 and LC_ALL=en_US.UTF-8. 

A.5.2 Linux Installer Issue with Unknown Host Error 

If your Linux server doesn't have proper hostname entries in the /etc/hosts file, you may get installer errors. 
The installer carries out an import operation to load the core minimal data into the repository database. This 
import operation can fail if the host is not configured. 

If the import operation fails during installation, the installation will also fail. However, there should be an 
installation.log in the root of the installation folder to help debug the problem. The installation.log is 
located here: 

<js-install>/installation.log 

An improperly configured hosts file typically causes error messages like these: 

Caused by: java.net.NoRouteToHostException: No route to host 

com.mysql.jdbc.exceptions.jdbc4.CommunicationsException: Communications link failure 
ERROR Caches146 - Unable to set iocalhost. This prevents creation of a GUID 
j ava.net.UnknownHostException 

org.quartz.SchedulerException: Couldn't get host name! 

To fix the /etc/hosts file: 

1. Include entries that look like these: 

127.0.0.1 Iocalhost.localdomain 

172.17.5.0 myhost.mydomain.com myhost 
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For instance: 

127.0,0.1 localhost.localdomain localhost 

.72.17.5.0 myhost.jaspersoft.com myhost 

2. You can also double check the file /etc/sysconfig/network (if it exists). In this file it would be similar 
to the following: 

HOSTNAME=myhost 

3. After fixing the /etc/hosts file, reinstall JasperReports Server. 

A.6 Installation Error with Windows Path 

If the path of the war archive exceeds the maximum length allowed by Windows, you'll get an error message 
like the one shown below. 

java.io.XOException: Cannot run program "C:\Program 

Files!Java!jdkx.x.x_xx\jre\bin\java.exe" : CreateProcess error=206, The filename 

at j ava.lang.ProcessBuilder.start(ProcessBuilder.j ava:460) 
at java.lang.Runtime.exec(Runtime.java:593) 

You'll need to move the war archive to reduce the path length. More information is available from Microsoft at: 
http ://msdn,micro soft.com/en-us/library/windows/desktop/aa3 65247(v=vs.85).aspx . 

A. 7 Mac OSX Issues 

A.7.1 Problem Starting JasperReports Server on Mac 

We have seen some issues caused by the improper shutdown of the Tomcat included with JasperReports Server. 
This may be caused by shutting the machine down while Tomcat is running. 

When the Tomcat scripts start Tomcat, they write a .pid (Process ID) file to the Tomcat folder. Tomcat uses this 
to determine whether the Tomcat instance is already running. When Tomcat is shutdown, this pid file is 
removed. However, if the pid file is not removed on shutdown, Tomcat will fail to start up. 

You may see this when you double-click the jasperServerStart.app startup. JasperReports Server seems to be 
starting up, but it never actually does. 

To recover from this issue, manually delete the pid file. 

Delete catalina.pid using Finder: 

1. Navigate to the <js-install>/tomcat/temp folder 

For instance: /Applications/jasperreports-server-cp-7.8.O/tomcat/temp 

2. Delete catalina.pid 

Delete the catalina.pid file using Terminal shell: 

1. Open a Terminal shell (Finder > Go > Utilities > Terminal Icon) 

2. Navigate to the <js-install>/tomcat/temp folder 

For instance: /Applications/jasperreports-server-cp-7.8.O/tomcat/temp 
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3. Enter the following command: 

rm catalina.pid 


To start and stop the PostgreSQL and Tomcat components separately from the command line 
shell: 

1. Open a Terminal shell (Finder > Go > Utilities > Terminal Icon). 

2. Navigate to the <js-install> folder. 

For instance: /Applications/jasperreports-server-cp-7.8.0 

3. To Start: 

./ctlscript start postgresql 
./ctlscript start tomcat 

4. To shutdown: 

./ctlscript stop 


./ctlscript stop tomcat 
./ctlscript stop postgresql 


A.8 Database-related Problems 

A.8.1 Database Privileges Required By JasperReports Server 


Install/upgrade process permissions: 

The JasperReports Server installation/upgrade processes and the repository database user need the following 
privileges to install and initialize the jasperserver repository database. 


Database Component 

Permissions Required 

databases 

CREATE 


DROP 

tables 

CREATE 

indexes 

ALTER 

constraints 

DROP 

data records 

INSERT 


UPDATE 


DELETE 


If you are upgrading in a restricted environment, your database administrator may need to give you temporary 
admin permissions for the upgrade. For example, if you are using PostgreSQL for your database, the database 
admin may use one of the following workarounds: 

• Add administrator credentials in the default master.properties file prior to upgrade and then replace them 
with jasperadmin credentials after upgrade. 
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• Prior to upgrade, grant create and drop permissions at the database server level for the jasperadmin user , 
then revoke those permissions after successful upgrade. 


A. 8.2 Database Connectivity Errors 

The most common problems encountered with a new JasperReports Server instance are database configuration 
problems. The connection may fail because the application server can't find the driver for the data source. For 
example, in a default installation of JasperReports Server, Tomcat looks for data source drivers in 
<js-install>/apache-tomcat/lib. If the driver's in a different location, put a copy of the driver in this 
directory and restart Tomcat. 

A.8.2.1 Testing the Database Connection 

The simplest database configuration problem is an incorrect user name or password. If you encounter database 
problems upon startup or login, check the user name and password by logging directly into your RDBMS as 
described below. 

You can connect to your database using the database configuration settings in JasperReports Server. This 
validates the database hostname, port, username, and password. 

If you're having trouble logging into JasperReports Server on the login page, check the existing users and 
passwords in the jasperserver. JlUser table. 

A.8.2.2 Logging into PostgreSQL 

Run the PostgreSQL client from the command line and try to connect to the database. For example: 

psql -tJ postgres jasperserver 

A.8.2.3 Logging into MySQL 

Run the MySQL client from the command line and try to log in directly as the root user, for example: 

<mysql>/bin/mysql -u root -p 

You're prompted for the password of the user you specified on the command line. 


A.8.3 Maximum Packet Size in MySQL 

If you're upgrading or importing into a MySQL database and your repository contains large objects like images, 
you may see an error like this: 

ERROR 1153 (08S01): Sot a packet bigger than 'max_allowed_packet' bytes 

The default max_allowed_packet on the MySQL server is 1M (one Megabyte = 1,048,576 bytes). The most 
effective fix is to change this value in the server configuration to accommodate the largest resource stored in 
your repository. The server configuration file is typically named my.cnf (or my .ini) and located in the MySQL 
root directory, but this may vary. Change the configuration setting to a larger value, for example: 

max_allowed_packet = 16M 

For more information, see http://dev.mysql.eom/doc/refinan/5.0/en/paeket-too-large.html . 

After changing this value, restart the MySQL server. Then perform the upgrade or import step again. 
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A.8.3.1 Connection reset by peer MySQL Error 

If you are using the MariaDB JDBC driver to connect to the MySQL database and get an error such as the 
following: 

Could not send query: 

Connection reset by peer: socket write error 

This message refers to the maximum packet size error described above. Follow those instructions. 


A.8.4 Case Sensitivity for Table and Column Names 

In some databases, table names are case-sensitive and “customer” and “Customer” are two different tables. 

If you're using a case-sensitive database for JasperReports Server, table names specified in query strings in the 
JRXML file of a saved report must match the table names used in the database. A mismatch when transferring 
data from one database to another may cause the capitalization of table names to change. 

In Windows MySQL, table and column names are not case-sensitive. 

In Linux MySQL, table and column names are case-sensitive. You can configure Linux MySQL to be non-case- 
sensitive by setting the configuration parameter lower_case_table_names to 1 in the my .ini or my.cnf file. 
For more information search the MySQL documentation for a section about identifier case sensitivity. 

Table and column names in PostgreSQL are case-sensitive. 


A.8.5 PostgreSQL: Job Scheduling Error 

If the Quartz settings in the PostgreSQL database aren't updated to specify the driver delegate class specific to 
PostgreSQL you'll get errors when you try and run a scheduled report. 

The errors will look like this: 

Error while fetching Quartz runtime information 

org.quartz.JobPersistenceException: Couldn't obtain triggers: Bad value for type int 
org.postgresql.util.PSQLException: Bad value for type int 

If you see this error, check your Quartz properties file in the following location: 

<tomcat>/webapps/jasperserver-ce/WEB-INF/js.quartz.properties 

Make sure the following property does not have the standard driver delegate, but instead has the PostgreSQL- 
specific driver delegate. It should look like the following for PostgreSQL: 

quartz.delegateClass=org.quartz.impl.j dbcj obstore.PostgreSQLDelegate 

A.8.6 Error Running a Scheduled Report 

If you run a scheduled report and save it as HTML or RTF, the resulting report may be quite large. If you are 
running MySQL and get the error shown here, the problem may be the default size of the MySQL blob 
datatype. 

JDBC exception on Hibernate data access 

org.hibernate.exception.GenericJDBCException: could not insert 
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You can increase the size of this datatype by updating your my.ini or my.cnf MySQL configuration file with the 
following setting: 

max_allowed_packet=32M 


A.8.7 Error Running a Report 

If you can log into JasperReports Server but encounter an error when running a report, browse the repository to 
identity and resolve the problem. 

One common problem with an individual report is the data source. To validate a data source connection: 

1. Log into JasperReports Server as a user with administrative permissions and locate the report unit that 
returns errors. 

2. Select the report and click the Edit button in the toolbar and identify the data source on the fourth edit 
page. 

3. Edit the data source in the repository and check its settings. 

4. Click the Test Connection button. 

If the connection tails, perhaps the application server can't find the driver for the data source. For example, 
in a default installation of JasperReports Server, Tomcat looks for data source drivers in <js-install>/apache- 
tomcat/lib. 

5. Test your report. If it still returns errors, edit the data source again and try checking other values, like the 
port used by the database. 

A.8.8 JDBC Driver Loading Error on Import/Export from WebLogic or WebSphere 

If you are using WebLogic or WebSphere and want to ran import/export from the command line, you need to 
manually copy the JDBC driver to the same location as the import/export scripts. If you have not copied these 
files, you may encounter the following error: 

Cannot load JDBC driver class 'tibcosoftware.jdbc.sqlserver.SQLServerDriver 1 

To fix this error, copy your database driver to the correct location: 

from: <j s-install>\buildomatic\confysouice\db\<your_database>\j dbc\ 

or 

<j s-install>\buildomatic\confysouice\db\<your_database>\native .j dbc\ 
to: <j s-install>\buildomatic\confysouice\iePro\lib 

A.9 Application Server-related Problems 

A.9.1 Memory Issues Running Under Tomcat 

These steps might solve problems related to the release of memory or to container tag pooling: 

1. Set the following parameter in the global $CATALINA_BASE/conf/web.xml: 

enablepooling = false 


TIBCO Software Inc. 


59 




TIBCO JasperReports Server Community Project Installation Guide 


2. Restart Tomcat. 


A.9.2 Java Out of Memory Error 

If you encounter a Java out of memory error, try increasing your Java heap size setting. See 4.1, “Setting JVM 
Options for Application Servers,” on page 39. As a minimum, add -Xms2048m -Xmx4096m to your JAVA_OPTS 
setting. You may need to increase this setting according to your usage. 

This Java option is set within the application server, so you must restart your application server. 

A.9.3 Configuration File Locations 

You'll find JasperReports Server configuration properties specific to your application server in the following 
files. 

Tomcat: <tomcat>/webapps/jasperserver/META-INF/context.xml 

<tomcat>/webapps/jasperserver/WEB-INF/hibemate.properties 

<tomcat>/apache-tomcat/webapps/j asperserver/WEB-INF/web .xml (JNDI config) 

<tomcat>/apache-tomcat/config/Catalina/localhost/jasperserver.xml (delete: see below) 

JBoss: <jboss>/standalone/deployments/jasperserver.war/WEB-INF/js-jboss7-ds.xml 

<jboss>/standalone/deployments/jasperserver.war/WEB-INF/hibemate.properties 

<jboss>/standalone/deployments/jasperserver.war/WEB-INF/web.xml 

<jboss>/standalone/deployments/jasperserver.war/WEB-INF/jboss-web.xml 

A.9.4 Tomcat Installed Using apt-get/yum 

A.9.4.1 Setting CATALINA_HOME 

If you're installing JasperReports Server to an instance of Tomcat that was installed using a package manager 
like apt-get, yum, or rpm, you can use the catalina_home and catalina_base properties found in your 
default master.properties file. 

Go to the section of the default_master .properties that looks like this: 

# Tomcat app server root dir 

appServerDir = C:\\Program FilesWApache Software FoundationW Tomcat 9.0 

# appServerDir = /home/devuser/apache-tomcat-9.0 

# if linux package managed tomcat instance, set two properties helow 

# CATALINA_HOME = /usr/share/tomcat9 

# CATALINA_BASE = /var/lih/tomcat9 

and change which lines are commented so it looks like this: 

# Tomcat app server root dir 

# appServerDir = C:\\Program FilesWApache Software FoundationW Tomcat 9.0 

# appServerDir = /home/devuser/apache-tomcat-9.0 

t if linux package managed tomcat instance, set two properties below 
CATALINA_HOME = /usr/share/tomcat9 
CATALINA_BASE = /var/lib/tomcat9 
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Note that you must set both catalina_home and catalina_base. 

A.9.4.2 Database Driver Location 

After installing JasperReports Server, make sure there's a copy of the database driver file in the 
/usr/share/tomcat9/webapps/jasperserver/WEB-INF/lib directory. If it's not there, copy the driver to this location. 
For example, for PostgreSQL, you can copy the driver from the 
<js-install>/buildomatic/conf_source/db/postgresql/jdbc directory. 


A.9.5 JBoss Modifications 

A.9.5.1 JBoss 7.0.0 Startup JDBC Version Error 

The installation with JBoss EAP 7.0.0 may fail with the following error: "Detected Elasticsearch JDBC jar hut 
cannot retrieve its version." In this case, you can remove the JAR file from the JasperReports Server WAR file s 
that the installation and startup can proceed. 

1. Edit the WAR file with the following command on Linux: 

zip -d jasperserver-pro.war WEB-INF/lib/x-pack-sql-jdbc-7.6.0.jar 
You can verify that the JAR file has been removed with the following Linux command: 
jar -tf jasperserver-pro.war | grep x-pack* 

2. Stop the JBoss app server. 

3. Delete the jasperserver-pro.war objects in the <jboss-eap-7.0>/standalone/deployments directory. 

4. Switch to the JRS buildomatic directory and re-deploy the JRS war file: 

./js-ant deploy-webapp-pro 

5. Restart the JBoss app server. 

A.9.5.2 JBoss 7 Startup Timeout Error 

JBoss 7 has a default startup time period. If your JBoss 7 takes longer than 60 seconds to start or deploy, you 
may receive the following error: 

"(DeploymentScanner-threads - 1) Bid not receive a response to the deployment 
operation within the allowed timeout period [60 seconds]. Check the server 
configuration file and the server logs to find more about the status of the 
deployment". 

To fix this, you need to increase your deployment-timeout setting as follows: 

1. Change to the JBoss standalone configuration directory. 

cd <jboss>/standalone/configuration 

2. Open the standalone .xml file. 

3. Look for the <subsystem xmlns="urn: jboss : domain: deployment-scanner: 1.1"> element, for 
example: 

<subsystem xmlns="urn:jboss:domain:deployment-scanner:1.1"> 

<deployment-scanner path="deployments" relative-to="jboss.server.base.dir" scan- 
interval "5 0 0 0"/> 

</subsystem> 
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4. Edit this to add or set the attribute deployment-timeout to the preferred time in seconds, for example: 
<subsystem xmlns="urn:jboss:domain:deployment-scanner:1.1"> 

<deployment-scanner path="deployments" relative-to="jboss.server.base.dir" scan- 
interval "5000" deployment-timeout= " 600 " /> 

</subsystem> 

5. Save the file. 

On server restart, your system will have the specified time to start up. 

A.9.5.3 Using a Non-default JBoss Profile 

If JBoss is your application server, and you’re using a profile other than the default, you need to set the 
jboss.profile property before running the js-install script in 3.3, “Installing the WAR File Using js-install 
Scripts,” on page 29: 

1. Open this buildomatic property file: 

<j s-install>/buildomatic/build_conf/default/app.srv.properties 

2. Uncomment the jboss.profile property and change the profile name as follows: 
from 

# jboss.profile = default 

to 

jboss.profile = <your_profile> 

A.9.5.4 Using JBoss with Non-Latin Characters 

If JBoss is your application server, and your organization is created with non-Latin characters, you will need to 
edit the standalone .xml configuration file. 

1 . Edit < jboss-home>/standalone/configuration/standalone.xml 

2. Add a new <system-properties> tag after the <extensions> tag, as shown in the following example. 

<extensions> 


</extensions> 

<system-properties> 

<property name="org. apache.catalina.connector.DRI_ENCODING" value="OTF-8"/> 

<property name="org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING" value="true"/> 
</system-properties> 


A.9.5.5 Maximum Post Size in Wildfly 

If you're upgrading or importing on some versions of Wildfly and your repository or other import file is large, 
the import may fail and the connection may be reset. In this case, you may need to set max-post-size. To do 
this, open the file <wildfly-home>standalone/configuration/standalone.xml and add or change the max-post¬ 
size attribute of the http-listener property, for example: 

<http-listener name="default" socket-binding="http" max-header-size="974247881" 
max-post-size="974247881"/> 
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A.9.6 Disabling User Session Persistence in Application Servers 

JasperReports Server stores non-serializable data in its user sessions, which can cause errors after restarting your 
application server: 

Exception loading sessions from persistent storage 
Cause: java.io.NotSerializableException ... 

The errors appear in the JasperReports Server log when users log in after the application server has been 
restarted. Users don't see the errors, and they have no impact on JasperReports Server operations. 

Because JasperReports Server user sessions are not persistent, you can configure your application server to 
disable persistence and avoid the error. For example, in Apache Tomcat, edit the file <tomcat>/conf7context.xml 
and locate the following lines. 

<!— Uncomment this to disable session persistence across Tomcat restarts —> 

<Manager pathname="" /> 

Remove the comment markers from lines 2 and 4 above, then restart Apache-Tomcat activate the change. For 
other application servers, refer to the product documentation. 


A. 10 Problems Importing and Exporting Data from the Repository 

A. 10.1 Exporting a Repository That Contains UTF-8 

You may see the following errors when you have international characters in repository objects, for example, in 
user IDs. 

A. 10.1.1 Error During Export 

An Upgrade usually requires exporting your database. If you're using MySQL and getting this null pointer 
exception, it may be caused by an incorrect character in the j s. j dbc. properties file: 
j ava.lang.NulXPointerException 

ResourceExporter.exportResource(ResourceExporter.java:258) 

Check the URL in this file in <js-install>buildomatic/build_conf7default/; it should look like this: 

j dbc:mysql://localhost:330 6/j asperserver?useUnicode=true&characterEncoding=UTF-8 

Note the ampersand &. It's incorrect if it appears as &amp; . The &amp; is correct only in an HTML or XML 
context. It's incorrect in a properties file. 
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If you can’t use the js-install scripts to create the JasperReports Server database and the sample databases, 
you can create them manually. Follow the instructions for your database to create the repository database and 
optional sample databases: 

• PostgreSQL 

• MySQL 

The commands in these sections have been tested at Jaspersoft, but the commands you need to use on your 
database instance may be different. 


B. 1 PostgreSQL 

To manually create the JasperReports Server database in PostgreSQL: 

1. On the Windows, Linux, or Mac command line, enter these commands: 

cd <js-install>/buildomatic/install_resources/sql/postgresql 
psql -U postgres -W 

postgres=#create database jasperserver encoding='utf8'; 

postgres=#\c jasperserver; 

postgres=#\i js-create.ddl 

postgres=#\i quartz.ddl 

postgres=#\q 

2. (Optional) Run the following commands if you want to install sample databases: 

cd <js^install>/buildomatlc/install_resources/sql/postgresql 
psql -U postgres -W 

postgres=#create database sugarcrm encoding='utf8'; 
postgres=#create database foodmart encodingsutf8'; 
postgres=#\c sugarcrm; 

postgres=#\i sugarcrm.sql; (first make sure the file is unzipped) 
postgres=#\c foodmart; 

postgres=#\i foodmart-postqresql.sql; (first make sure the file is unzipped) 

postgres=#\i supermart-update.sql; 

postgres=#\q 
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3. If you didn't install the optional sample databases, complete the installation with these commands: 

cd <js-install>/buildomatic 
js-ant import-minimal-ce 
js-ant deploy-webapp-ce 

If you installed the optional sample databases, complete the installation with these commands: 

cd <js-install>/buildomatic 
js-ant import-sample-data-ce 
js-ant deploy-webapp-ce 

For more information about executing the Ant scripts, see 3.9, “Installing the WAR File Manually,” on 
page 35. 


4. Set Java JVM Options (required), as described in 4.1, “Setting JVM Options for Application Servers,” on 
page 39. 


.2 MySQL 


To manually create the JasperReports Server database in MySQL: 

You can use the MySQL client software, mysql.exe or mysql, to interact with the MySQL database. 



For specific details on connecting to the MySQL database and setting privileges for databases and 
db users, please refer to the documentation provided with your database. 


1. On the Windows, Linux, or Mac command line, enter the following commands to create and initialize the 
JasperReports Server database. 

cd <js-install>/buildomatio/install_resources/sql/jitysql 
mysql -u root -p 

mysql>create database jasperserver character set utf8; 

mysql>use jasperserver; 

mysql>source js-create.ddl 

mysql>souree quartz.ddl 

mysql>exit 

2. (Optional) Run these commands to install sample databases: 

cd <j s-install>/buildomatic/install_resources/sql/mysql 

mysql -u root -p 

mysql>create database sugarcrm; 

mysql>create database foodmart; 

mysql>use sugarcrm; 

mysql>source sugarcrm.sql;(first make sure the file Is unzipped) 
mysql>use foodmart; 

mysql>source foodmart-mysql.sql; (first make sure the file is unzipped) 

mysql>source supermart-update.sql; 

mysql>exit 
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3. If you didn't install the optional sample databases, complete the installation with these commands: 

cd <js-install>/buildomatic 
js-ant import-minimal-ce 
js-ant deploy-webapp-ce 

If you installed the optional sample databases, complete the installation with these commands: 

cd <js-install>/buildomatic 
js-ant import-sample-data-ce 
js-ant deploy-webapp-ce 

For more information about executing the Ant scripts, see 3.9, “Installing the WAR File Manually,” on 
page 35. 

4. Set Java JVM Options (required), as described in 4.1, “Setting JVM Options for Application Servers,” on 
page 39. 
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